Skip to main content
POST
/
v1
/
shipping
/
retailers
Create Retailer
curl --request POST \
  --url https://{base_url_domain}/api/global/v1/shipping/retailers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "walmart",
  "name": "Walmart",
  "status": "active",
  "fulfillment_model": "wholesale",
  "merchant": {
    "code": "acme_inc",
    "name": "ACME Inc.",
    "custom_fields": {
      "is_gift": {
        "value": true
      },
      "order_details": {
        "value": "test details"
      },
      "department": {
        "id": 3,
        "label": "Shipping"
      },
      "priority_levels": [
        {
          "id": 1,
          "label": "Urgent"
        },
        {
          "id": 2,
          "label": "High"
        }
      ],
      "cost_of_goods": {
        "amount": 156.99,
        "currency": "USD"
      },
      "assigned_user": {
        "value": 42
      }
    }
  },
  "legal_name": "Walmart Inc.",
  "dba": "Walmart Marketplace",
  "default_duties_payor": "recipient",
  "default_shipping_method": "fedex_FEDEX_GROUND",
  "allowed_shipping_methods": [
    "fedex_FEDEX_GROUND",
    "ups_GND"
  ],
  "default_tpb_group_id": 5,
  "routing_guide_notes": "<string>",
  "custom_fields": {
    "is_gift": {
      "value": true
    },
    "order_details": {
      "value": "test details"
    },
    "department": {
      "id": 3,
      "label": "Shipping"
    },
    "priority_levels": [
      {
        "id": 1,
        "label": "Urgent"
      },
      {
        "id": 2,
        "label": "High"
      }
    ],
    "cost_of_goods": {
      "amount": 156.99,
      "currency": "USD"
    },
    "assigned_user": {
      "value": 42
    }
  },
  "created_at": "2017-07-21T17:32:28Z",
  "updated_at": "2017-07-21T17:39:43Z"
}
'
{
  "resource": {
    "type": "<string>",
    "id": 1
  },
  "meta": {
    "processing_time": 123
  }
}

Authorizations

​
Authorization
string
header
required

Generate a JWT access token through a Custom Global Integration and provide it with each request in the Authorization header prefixed with "Bearer" and then a single space.

Body

application/json

An object conforming to the Retailer schema to be created.

A Retailer represents a B2B retail partner for a merchant, including fulfillment defaults and retailer-specific custom fields.

​
code
string

Unique retailer code within the merchant.

Required string length: 1 - 64
Example:

"walmart"

​
name
string

Retailer display name.

Required string length: 1 - 255
Example:

"Walmart"

​
status
enum<string>
default:active

Retailer lifecycle status.

Available options:
active,
on_hold,
terminated
Example:

"active"

​
fulfillment_model
enum<string>
default:wholesale

Default fulfillment model used for this retailer.

Available options:
wholesale,
drop_ship,
mixed
Example:

"wholesale"

​
merchant
Merchant · object

The merchant that owns this retailer.

​
parent_retailer
RetailerRef · object

Optional parent retailer reference. The parent must belong to the same merchant.
Optional Field

​
legal_name
string | null

Legal retailer name.
Optional Field

Maximum string length: 255
Example:

"Walmart Inc."

​
dba
string | null

Doing-business-as name.
Optional Field

Maximum string length: 255
Example:

"Walmart Marketplace"

​
default_duties_payor
enum<string> | null

Default duties payor for order-integration defaults.
Optional Field

Available options:
shipper,
recipient,
third_party
Example:

"recipient"

​
default_shipping_method
string | null

Default shipping method for order-integration defaults.
Optional Field

Maximum string length: 255
Example:

"fedex_FEDEX_GROUND"

​
allowed_shipping_methods
string[] | null

Shipping methods allowed when this retailer is selected.
Optional Field

Example:
["fedex_FEDEX_GROUND", "ups_GND"]
​
default_tpb_group_id
integer<int32> | null

Default shipping third-party billing group ID for order-integration defaults.
Optional Field

Required range: x >= 1
Example:

5

​
routing_guide_notes
string | null

Free-form routing-guide notes.
Optional Field

Maximum string length: 65535
​
custom_fields
object

Custom fields associated with the retailer in script format. Each field contains a code and value, with additional properties depending on the field type.
Optional Field

Example:
{
  "is_gift": { "value": true },
  "order_details": { "value": "test details" },
  "department": { "id": 3, "label": "Shipping" },
  "priority_levels": [
    { "id": 1, "label": "Urgent" },
    { "id": 2, "label": "High" }
  ],
  "cost_of_goods": { "amount": 156.99, "currency": "USD" },
  "assigned_user": { "value": 42 }
}
​
created_at
string<date-time> | null

The date and time the retailer was created in RFC 3339 section 5.6 notation.
Optional Field

Example:

"2017-07-21T17:32:28Z"

​
updated_at
string<date-time> | null

The date and time the retailer was last updated in RFC 3339 section 5.6 notation.
Optional Field

Example:

"2017-07-21T17:39:43Z"

Response

Created - The resource was created successfully.

​
resource
object

An object describing the resource that was created.

​
meta
object