API ReferenceIOSSRegister or re-file an IOSS number

Register or re-file an IOSS number

POST/api/v1/ioss idempotent

Register an IOSS number to the authenticated account and submit its registration details to YunExpress for filing. Requires shipments:write and Idempotency-Key. This files an existing IOSS number with the carrier; it does not issue a new tax number. The same number can be submitted again to update supplied details or retry a failed filing. Omitted fields preserve stored values; registration fields merge with saved details. New numbers default to own; platform requires platform_name in this request or the saved record. At most 10 active numbers are allowed per account; a disabled number is reactivated if capacity permits. Labels must be unique within the account. The account default is not changed. Live registrations immediately appear in OMS Settings, and can be sent as ioss_number when quoting or creating a shipment. HTTP 200 confirms the local registration was saved, not that the carrier approved it. filing.status and filing.filed describe the last confirmed carrier result: approved confirms approval; pending_review or submitted does not. A later failed attempt preserves an earlier approval: filing.status remains approved and filing.filed remains true. filing.status is failed only when no confirmed filing is available. Read filing.last_attempt_status separately: in_progress, succeeded or failed; it may be null or absent on legacy or simulated records. A latest attempt marked succeeded does not itself mean approval. For the latest failed attempt, filing.error_code remains IOSS_FILING_FAILED, even when an earlier approval is retained. Optional filing.carrier_error_code is a nullable 8–10 digit string that preserves leading zeroes. Known codes include 02039207 (the YunExpress IOSS agreement has not been accepted) and 02039188 (the registration country is not an EU member). filing.carrier_error_message uses fixed safe text for known codes and a generic explanation for unknown codes or transport failures; it never returns the original provider response. Diagnostic fields are null when there is no current failure. Clients must accept absent or null optional diagnostics and unknown carrier codes. The saved registration is retained after a failed attempt. Correct the details or retry with a new idempotency key. A replay with the same key and body returns the first response for 24 hours, including its original filing result; use GET for the latest recorded state, not a fresh carrier status query. Different content with the same key is 409. Another IOSS mutation in progress or unavailable registration storage or locking returns 503; retry the same request with the same idempotency key after a short delay. Sandbox prerequisite: with a mk_test_* key, first register the IOSS number through POST /v1/ioss for the same account. Only after this succeeds may you explicitly send that number as ioss_number to POST /v1/rates and POST /v1/shipments. Test keys use a separate sandbox registry: a number in live OMS Settings, the live registry or the live account default alone does not authorize a sandbox override, which returns 400 IOSS_NOT_OWNED until registered in sandbox. The registration returns livemode: false and filing.status equal to simulated; it never files with the carrier or changes live registrations or the live account default. Sandbox registration does not authorize live overrides. Existing account-default fallback behavior when ioss_number is omitted is unchanged. Registration document attachments are not supported by this endpoint.

Parameters

ioss_number*

stringbody

IOSS number: IM followed by 10 digits. Registers it to your account or re-files an existing number.

label

stringbody

Optional account-unique display label, 1–24 characters. Cannot contain a comma or double quote. Yun (case-insensitive) is reserved. Omitted on re-filing preserves the stored label.

platform_name

stringbody

Marketplace platform name, up to 255 characters. Required for a new platform IOSS; an existing platform name can be reused. Only valid when the resulting type is platform.

registration

objectbody

Optional carrier registration details: company (max 50 characters), country_code (two-letter EU27 member code), street (max 255), city (max 50), province (max 50), postal_code (max 20), phone_number (max 50), email (valid email, max 100). Supplied fields merge into stored details; omitted or blank optional fields preserve existing values. No attachment URLs are accepted.

type

enum (own | platform)body

Defaults to own for a new number. Omitted fields preserve stored values when re-filing.

Responses

Success body

{
  "status": 200,
  "message": "OK",
  "data": {
    "ioss_number": "IM1234567890",
    "label": "Own IOSS",
    "type": "own",
    "registration": {
      "company": "Example Trading Ltd",
      "country_code": "DE",
      "street": "Example Street 1",
      "city": "Berlin",
      "postal_code": "10115",
      "email": "customs@example.com"
    },
    "platform_name": null,
    "is_default": false,
    "status": "active",
    "livemode": false,
    "filing": {
      "status": "simulated",
      "filed": false,
      "simulated": true,
      "error_code": null,
      "carrier_error_code": null,
      "carrier_error_message": null,
      "last_attempt_status": null,
      "filed_at": null,
      "last_attempt_at": null
    },
    "created_at": "2026-11-03T08:00:00.000Z",
    "updated_at": "2026-11-03T08:00:00.000Z"
  }
}

Returned object

Field	Type	Sample
status	number	200
message	string	OK
data	object	{11 keys}