Skip to content
Guides
/
/
Create Suppliers
Last updated

Create Suppliers

Add new suppliers to your account with company and contact information. Suppliers are used when creating purchase orders to identify where products are being ordered from.

Create a Supplier

Use the POST method with /v2/suppliers to create a new supplier with company and contact information.

Request Body Properties

PropertyTypeRequiredDescription
supplier_namestringRequiredName of the supplier company
supplier_emailstring (email)OptionalEmail address for sending purchase orders
address_line_1stringOptionalFirst line of address
address_line_2stringOptionalSecond line of address
citystringOptionalCity
statestringOptionalState or province code
postal_codestringOptionalPostal or ZIP code
country_codestringOptionalISO 3166-1 alpha-2 country code
contact_namestringOptionalPrimary contact person's name
contact_phonestringOptionalContact phone number

Response

On success, returns an object with the newly created supplier_id:

{
  "supplier_id": "se-567"
}

Example Request & Response

POST /v2/suppliers

curl -i -X POST \
  https://api.shipstation.com/v2/suppliers \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "supplier_name": "Acme Widgets Inc",
    "supplier_email": "orders@acmewidgets.com",
    "address_line_1": "123 Main St",
    "address_line_2": "Suite 100",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country_code": "US",
    "contact_name": "John Doe",
    "contact_phone": "512-555-0100"
  }'

Validation Rules

Required Fields

  • supplier_name uniq supplier name must be provided and cannot be empty

Email Validation

  • supplier_email must be a valid email format if provided
  • Format: name@domain.com

Country Codes

  • country_code must be a valid ISO 3166-1 alpha-2 code
  • Examples: "US", "CA", "GB", "DE", "FR", "AU"

Phone Numbers

  • No strict format required - use your preferred format
  • Include country code for international numbers (+44, +1, etc.)
  • Include extensions if needed (555-0100 ext 123)

Error Handling

Common errors when creating suppliers:

400 Bad Request

  • Missing supplier_name
  • Invalid country code
  • Email format validation failure

Integration Workflow

Setup New Vendor Relationship

  1. Collect Information

    • Get official name and email from supplier
    • Request complete address for shipping origin tracking
    • Obtain primary contact details

  2. Create Supplier Record

    POST /v2/suppliers
{
  "supplier_name": "New Vendor Co",
  "supplier_email": "orders@newvendor.com",
  ...
}

  3. Store Supplier ID

    • Save the returned supplier_id
    • Use in future purchase orders

  4. Create First Purchase Order

    • Test the supplier by creating a purchase order
Previous page
Next page