> ## Documentation Index > Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Retailer > Creates a new `Retailer`. ## OpenAPI ````yaml POST /v1/shipping/retailers openapi: 3.0.3 info: title: ShipStream version: '1.0' license: name: Commercial (Copyright 2025 - All Rights Reserved) url: https://shipstream.io contact: name: ShipStream Support email: help@shipstream.io termsOfService: https://shipstream.io/legal/api-terms/ servers: - url: https://{base_url_domain}/api/global description: Direct API Url variables: base_url_domain: default: example.shipstream.app description: >- The fully qualified domain name for your ShipStream WMS instance. This is either a custom domain, or a subdomain of shipstream.app, and will be the same as the domain name for the page which you use to login to ShipStream WMS. security: - ShipStream_bearerAuth: [] tags: - name: Warehouses x-displayName: Warehouses - name: Products x-displayName: Products - name: ProductProfiles x-displayName: ProductProfiles - name: HandlingClasses x-displayName: HandlingClasses - name: Locations x-displayName: Locations - name: LocationTags x-displayName: LocationTags - name: SlotTypes x-displayName: SlotTypes - name: Levels x-displayName: Levels - name: HoldReasons x-displayName: HoldReasons - name: Holds x-displayName: Holds - name: Replenishment x-displayName: Replenishment - name: LocationProfiles x-displayName: LocationProfiles - name: SlottingRules x-displayName: SlottingRules - name: Deliveries description: Every thing about a Delivery Receiving x-displayName: Deliveries - name: Shipments x-displayName: Shipments - name: Orders x-displayName: Orders - name: Retailers x-displayName: Retailers - name: Users x-displayName: Users - name: User Roles x-displayName: User Roles - name: Merchants x-displayName: Merchants - name: Healthcheck x-displayName: Healthcheck paths: /v1/shipping/retailers: post: tags: - Retailers summary: Create Retailer description: Creates a new `Retailer`. operationId: createRetailer requestBody: required: true description: An object conforming to the `Retailer` schema to be created. content: application/json: schema: $ref: '#/components/schemas/Shipping_API_v1_Retailer' responses: '201': $ref: '#/components/responses/Shipping_API_v1_201-created-single' '400': $ref: '#/components/responses/Shipping_API_v1_400-bad-request' '422': $ref: '#/components/responses/Shipping_API_v1_422-unprocessable' '500': $ref: '#/components/responses/Shipping_API_v1_500-internal-server-error' components: schemas: Shipping_API_v1_Retailer: title: Retailer type: object description: >- A `Retailer` represents a B2B retail partner shared by all merchants, including fulfillment defaults and retailer-specific custom fields. properties: type: type: string enum: - Retailer readOnly: true description: >- This is a read-only property that describes the type of object in the response body. id: type: integer format: int32 minimum: 1 example: 123 readOnly: true description: >- The internal `id` property used as a path parameter in a resource lookup. code: type: string minLength: 1 maxLength: 64 example: walmart description: Globally unique retailer code. name: type: string minLength: 1 maxLength: 255 example: Walmart description: Retailer display name. status: type: string enum: - active - archived default: active example: active description: >- Retailer lifecycle status. Archived retailers are hidden from lists by default and cannot be assigned to new orders. fulfillment_model: type: string enum: - wholesale - drop_ship - mixed default: wholesale example: wholesale description: Default fulfillment model used for this retailer. parent_retailer: allOf: - $ref: '#/components/schemas/Shipping_API_v1_RetailerRef' nullable: true description: >- Optional parent retailer reference. Any non-archived retailer may serve as the parent.\ `Optional Field` legal_name: type: string nullable: true maxLength: 255 example: Walmart Inc. description: |- Legal retailer name.\ `Optional Field` dba: type: string nullable: true maxLength: 255 example: Walmart Marketplace description: |- Doing-business-as name.\ `Optional Field` default_duties_payor: type: string nullable: true enum: - shipper - recipient - third_party example: recipient description: |- Default duties payor for order-integration defaults.\ `Optional Field` default_shipping_method: type: string nullable: true maxLength: 255 example: fedex_FEDEX_GROUND description: |- Default shipping method for order-integration defaults.\ `Optional Field` allowed_shipping_methods: type: array nullable: true items: type: string example: - fedex_FEDEX_GROUND - ups_GND description: |- Shipping methods allowed when this retailer is selected.\ `Optional Field` routing_guide_notes: type: string nullable: true maxLength: 65535 description: |- Free-form routing-guide notes.\ `Optional Field` custom_fields: allOf: - $ref: '#/components/schemas/Shipping_API_v1_sales_custom_fields' nullable: true description: >- 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` created_at: allOf: - $ref: '#/components/schemas/Shipping_API_v1_created_at-optional' description: >- The date and time the retailer was created in RFC 3339 section 5.6 notation.\ `Optional Field` updated_at: allOf: - $ref: '#/components/schemas/Shipping_API_v1_updated_at-optional' description: >- The date and time the retailer was last updated in RFC 3339 section 5.6 notation.\ `Optional Field` required: - type - id additionalProperties: false Shipping_API_v1_RetailerRef: title: RetailerRef type: object description: Reference a `Retailer` by `id`. properties: type: type: string enum: - Retailer example: Retailer id: type: integer format: int32 minimum: 1 example: 2 description: >- The internal `id` property used as a path parameter in a resource lookup. required: - type - id additionalProperties: false Shipping_API_v1_sales_custom_fields: type: object description: >- Custom field values for the order, keyed by field code. The format of each value depends on the field's input type: - **select**: `{"id": , "label": ""}` - **multiselect**: `[{"id": , "label": ""}, ...]` - **currency**: Uses the Monetary type `{"amount": , "currency": ""}` - **boolean**: `{"value": }` - **text/multiline-text/email/url/date**: `{"value": ""}` - **number**: `{"value": }` - **admin-user/client-user**: `{"value": }` (user ID) additionalProperties: $ref: '#/components/schemas/Shipping_API_v1_custom_field_value' 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 Shipping_API_v1_created_at-optional: type: string format: date-time description: >- The date and time the object was created in RFC 3339 section 5.6 notation.\ `Optional Field` example: '2017-07-21T17:32:28Z' nullable: true readOnly: true Shipping_API_v1_updated_at-optional: type: string format: date-time description: >- The date and time the object was last updated in RFC 3339 section 5.6 notation. example: '2017-07-21T17:39:43Z' nullable: true readOnly: true Shipping_API_v1_custom_field_value: description: Union type for all possible custom field value formats. anyOf: - $ref: '#/components/schemas/Shipping_API_v1_custom_field_scalar_value' - $ref: '#/components/schemas/Shipping_API_v1_Monetary' - $ref: '#/components/schemas/Shipping_API_v1_custom_field_select_option' - $ref: '#/components/schemas/Shipping_API_v1_custom_field_multiselect_value' Shipping_API_v1_custom_field_scalar_value: type: object description: |- A wrapper for scalar custom field values. The value type depends on the field's input type: - **boolean**: boolean value - **text/multiline-text/email/url/date**: string value - **number**: number value - **admin-user/client-user**: integer value (user ID) required: - value properties: value: description: The field value. Type varies based on field configuration. oneOf: - type: boolean - type: string - type: number - type: integer additionalProperties: false Shipping_API_v1_Monetary: title: Monetary type: object nullable: true properties: amount: type: number description: This is the monetary value.. format: float example: 99 currency: type: string description: An ISO 3166-1 alpha-3 currency code. example: USD Shipping_API_v1_custom_field_select_option: type: object description: A selected option for select type fields. required: - id - label properties: id: type: integer description: The option ID. label: type: string description: The display label for the selected option. additionalProperties: false Shipping_API_v1_custom_field_multiselect_value: type: array description: Array of selected options for multiselect type fields. items: $ref: '#/components/schemas/Shipping_API_v1_custom_field_select_option' responses: Shipping_API_v1_201-created-single: description: Created - The resource was created successfully. content: application/json: schema: type: object properties: resource: type: object description: An object describing the resource that was created. properties: type: type: string description: A resource type identifier. id: type: number format: int32 example: 1 description: The primary key ID of the resource created. meta: type: object properties: processing_time: type: number description: >- Total time in which request is processed and response is sent back. format: float additionalProperties: false Shipping_API_v1_400-bad-request: description: >- The request was invalid. The client must change the request. See the response body for more details. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - parser - parameters - openapi message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: parameters message: The supplied parameters are invalid. Shipping_API_v1_422-unprocessable: description: >- There was an error processing the request. See the response body for more details. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: type: type: string description: The error type code. enum: - application - unable_to_process message: type: string description: An English sentence describing the error type. details: type: array description: >- An array of objects describing which keys are responsible for the error and detailed messages describing why they are not valid. items: type: object properties: key: type: string description: The path to the key which relates to the error. message: type: string description: >- An English sentence describing the details of the error. additionalProperties: false additionalProperties: false minItems: 1 additionalProperties: false example: errors: - type: unable_to_process message: There was an error processing the request. Shipping_API_v1_500-internal-server-error: description: >- Internal Server Error - Something wrong happened at server side. Contact server administrator for more details. securitySchemes: ShipStream_bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- 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. ````