Create a company location

POST/v1/api/store/{team_slug}/setting/location

v1Operation ID v1_public_location_store

Adds a company location and returns it. It doesn't hold stock; make it a warehouse with Set a location as a warehouse. The team's first location becomes its primary location; to move the primary role later, call Set the primary location.

Company locations are the team's own addresses. Each one can play several parts:

• Primary location (is_primary): the team's primary billing address. There is always exactly one.
• Warehouse (hold_stock): a location that holds stock. Turning a location into a warehouse is permanent. How many warehouses a team can have depends on its plan.
• Default warehouse (is_default_warehouse): the warehouse a new sales order uses when its customer has no default warehouse. Without one, YoPrint uses the first warehouse.
• Tax nexus (nexus): a place where the team collects sales tax. For US-plan teams with Auto Tax, Auto Tax looks up rates only when the team has a current US location with nexus.

Orders, purchase orders, stock and stock adjustments refer to a location by its id, so editing a location changes it everywhere it is used.

Permission

Needs the Manage Settings permission.

Business rules

• label, address1 and country_code are required.
• For US and Canadian addresses, state or state_code must be a real state or province. Send either one and YoPrint fills in the other; when you send both, they must match.

Side effects

• A new location has tax nexus unless you send nexus: false. For US-plan teams this can turn on Auto Tax rate lookups.

Path parameters

• team_slugstringrequired

  Your team slug, shown as Team ID next to your API key in Profile.

  • Example your-team

Request body

application/json, required.

• address1stringrequired
• country_codestringrequired

  The two-letter country code, such as US. Saved in capitals.

• labelstringrequired

  A name for the location.

• address2string
• citystring
• countrystring

  The country name. Left out, none is stored, and answers show the name for country_code.

• is_primaryboolean

  Optional and ignored: use Set the primary location.

• nexusboolean

  Whether the team collects sales tax here. Defaults to true.

• notestring
• postcodestring
• statestring | null

  The state or province name. For US and Canadian addresses it must be a real state or province; send it or state_code, and YoPrint fills in the other.

• state_codestring | null

  The state or province code, such as IL. Saved in capitals.

Response

200Successful response.

• dataobjectrequired
  Child fields (31)

  • address1string | nullrequired
  • citystring | nullrequired
  • country_codestring | nullrequired
  • hold_stockbooleanrequired

    Whether it is a warehouse that holds stock. Permanent once set.

  • idstringrequired
  • is_current_sourcebooleanrequired

    False for deleted or replaced rows.

  • is_default_warehousebooleanrequired

    The default warehouse for new sales orders.

  • is_primarybooleanrequired

    The team's primary location: its primary billing address. Exactly one.

  • labelstring | nullrequired
  • nexusbooleanrequired

    Whether the team collects sales tax here (tax nexus).

  • revision_numberintegerrequired

    Goes up by one on every saved change. Send it back as base_revision_number to avoid overwriting someone else's edit.

  • rolestringrequired

    Always store_location for company locations.

  • trashedbooleanrequired

    True for a deleted location.

  • address2string | null
  • address_family_idstring | null

    Groups an address with the versions that replaced it.

  • copied_from_address_idstring | null

    The address this one replaced, if any.

  • countrystring | null
  • external_typestring | null
  • is_externalboolean
  • notestring | null
  • owner_idstring | null

    For company locations, the team, encoded with the team's own hash ids. It is not the same string as the team id that Get your company details returns.

  • owner_typestring
  • postal_can_validateboolean
  • postal_is_validboolean
  • postal_validatedboolean
  • postcodestring | null
  • sourcestring
  • statestring | null
  • state_codestring | null
  • superseded_atstring (date-time) | null

    When it was replaced, if it was.

  • superseded_by_address_idstring | null

    The address that replaced this one, if any. Company locations are edited in place, so this is normally null.

• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

  When

  The API key is missing or wrong.

  Fix

  Send your personal API key as Authorization: Bearer YOUR_API_KEY.

• 403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.

  When

  Your permission group lacks Manage Settings. This 403 has a short body, {"message": "Insufficient Permission"}, without success or error.

  Fix

  Ask the team owner to give your permission group Manage Settings.

• 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

• 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

  When

  A required field is missing, or a US or Canadian state is unknown or doesn't match state_code ("Select a valid United States or Canada state/province."). error.code is validation_failed, and error.fields names each field with its messages.

  Fix

  Fix the fields listed in error.fields and send the request again.

Related

• PATCHSet a location as a warehouse/v1/api/store/{team_slug}/setting/location/{id}/hold_stock
• PATCHSet the primary location/v1/api/store/{team_slug}/setting/location/{id}/primary

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/location' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "address1": "100 Example Street",    "city": "Springfield",    "country_code": "US",    "is_primary": false,    "label": "Warehouse 2",    "nexus": true,    "postcode": "62701",    "state": "Illinois",    "state_code": "IL"  }'

Example response 200

Response

{
  "data": {
    "address1": "100 Example Street",
    "address2": null,
    "address_family_id": null,
    "city": "Springfield",
    "copied_from_address_id": null,
    "country": "United States",
    "country_code": "US",
    "external_type": null,
    "hold_stock": false,
    "id": "U4jnocbiJfXxQ9",
    "is_current_source": true,
    "is_default_warehouse": false,
    "is_external": false,
    "is_primary": false,
    "label": "Warehouse 2",
    "nexus": true,
    "note": null,
    "owner_id": "U9KHQle41wSkHO",
    "owner_type": "team",
    "postal_can_validate": false,
    "postal_is_valid": false,
    "postal_validated": false,
    "postcode": "62701",
    "revision_number": 1,
    "role": "store_location",
    "source": "company_location",
    "state": "Illinois",
    "state_code": "IL",
    "superseded_at": null,
    "superseded_by_address_id": null,
    "trashed": false
  },
  "status": 200,
  "success": true
}