Add a location to a company
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Path Parameters
Body
THE ADDRESS IS ENTIRELY OPTIONAL, deliberately: an ERP push routinely creates the org chart before the addresses arrive, and refusing the row would mean the hierarchy cannot be synced at all until someone types one. A location with no address simply cannot be shipped to. company_id is refused here by name because it comes from the path, and price_list_id is refused because a location reaches pricing by naming a CUSTOMER GROUP, which a price list already targets. There is no second targeting path, so a price_list_id here would have had no effect on any cart and no error either.
Required and must not be blank. Your label for the site, such as "Head Office" or "Bristol Depot".
THE NEGOTIATED-PRICING POINTER, and the one field on this family that costs a second scope. Naming it, or clearing it with null, decides what every buyer at this location is charged, so it requires write_pricing IN ADDITION TO write_companies and answers 403 insufficient_scope without both. The id must name a customer group in THIS store; anything else is 422, because the database foreign key does not enforce the tenant. Null means no negotiated pricing, which is the ordinary state of a location buying at the store's list prices.
Optional. Clearable with null.
Optional. Clearable with null.
Optional. Clearable with null.
Optional. Clearable with null.
Optional. Clearable with null.
Optional. Stored and served exactly as sent, with no case normalisation, so a read never disagrees with the write that preceded it.
Optional. Clearable with null.
The BUYER's own registration (VAT, GSTIN, ABN). Per location rather than per company, because a group trading in two countries registers separately in each.
NULL AND ZERO ARE DIFFERENT ANSWERS AND THIS API KEEPS THEM APART. Null means no terms have been agreed; 0 means DUE ON RECEIPT. Omitting the key leaves it null rather than defaulting to 0, because a default would state a term nobody negotiated and put every unconfigured account on the strictest one. Negative values are a 400.
x >= 0Optional, defaults to false. Setting it true DEMOTES whichever location currently holds the flag, in the same transaction, because at most one default is allowed per company. It therefore changes a location this call never named.
Response
Created