Industrial Fulfillment API (1.0.0-beta)

Download OpenAPI specification:Download

A single request order submission API.

The API allows to create orders from simple product definitions in a single request. It also provides resources to keep track of existing orders.

FAQ / Terms and Conditions

Authentication

oauth2

The following curl command shows how a token can be retrieved.

All requests need to set a proper non-empty User-Agent header that helps to indentify your application, e.g. curl/.* is not allowed.

We use OAuth's client credentials flow as described in RFC6749 Sec. 4.4.

Note that we will provide the required credentials for you, i.e. API_KEY and API_SECRET, when you register as a merchant.

$ curl\
  --silent\
  --user $API_KEY:$API_SECRET\
  --header 'Accept: application/json'\
  --data grant_type=client_credentials\
  --data scope='industrial-fulfillment.read industrial-fulfillment.write'\
  --data client_id=$API_KEY\
  https://auth.spreadshirt.net/oauth/token | jq .access_token

Scopes are provided as a comma separated as defined in RFC6749 Sec. 3.3.

The command above will print a JWT in this format: <header>.<payload>.<signature>. This token must be passed to all secured resources as value of the Authorization header, e.g. Authorization: Bearer <jwt-token>.

Note that tokens need to be renewed, the expiry time in seconds is shown in the expires_in field of the token response. Token renewal works exactly as requesting a new one, i.e. sending a POST request against the /token resource.

Following is an example token response:

{
  "access_token": "abc.def.ghj",
  "token_type": "bearer",
  "expires_in": 86399,
  "scope": "industrial-fulfillment.read industrial-fulfillment.write",
  "api_key": "3bc20c47-80eb-474f-8b2c-62fc85ea5531",
  "api_key_features": ["1", "2"],
  "jti": "90e47c06-8340-4e90-bdeb-c0079baf1743"
}

access_token is the token you need to supply to the API, expires_in is the expiry time of the token. All other fields are internal and may change without notice.

Security scheme type: OAuth2
clientCredentials OAuth Flow
Token URL: https://auth.spreadshirt.com/oauth/token
Scopes:
  • industrial-fulfillment.read -

    Access right needed to read from the industrial fulfillment api.

  • industrial-fulfillment.write -

    Access right needed to write to the industrial fulfillment api.

Orders

The main focus of the Industrial Fulfillment API is the creation and retrieval of orders.

Submit an order

Submit a simple order.

Following is an example that shows the order payload for a large black mens t-shirt with print on front and back. The stock keeping unit ID can be gathered from the product types resource.

{
    "external-order-id": "84681638-388c-4c58-8b49-325ffed37928",
    "currency": "USD",
    "items": [{
        "quantity": 1,
        "stock-keeping-unit": "812-4-2",
        "price": "19.00",
        "configuration": [{
                "type": "design",
                "side": "front",
                "align": "center-top",
                "content": {
                    "url": "https://api.spod.com/assets/fox_2048.png"
                }
            },
            {
                "type": "design",
                "side": "back",
                "align": "center-top",
                "content": {
                    "url": "https://api.spod.com/assets/dog_2048.png"
                }
            }
        ]
    }],
    "shipping": {
        "type": "standard",
        "price": "3.99",
        "address": {
            "first-name": "John",
            "last-name": "Doe",
            "street": "00679 Saige Coves",
            "street-annex": "Suite 986",
            "city": "Purdybury",
            "country-code": "US",
            "state": "AL",
            "zip-code": "01727"
        }
    }
}

On success a response similar to this is returned:

{
  "external-order-id": "c5385994-3c19-404f-80ef-a328242d748c",
  "url": "https://api.spod.com/orders/c5385994-3c19-404f-80ef-a328242d748c"
}

Details, like the current processing state of the order, can be retrieved from the given url.

Authorizations:
oauth2 (industrial-fulfillment.write)
Request Body schema: application/json

A simple order request that contains order items with their configuration and the customers shipping details

external-order-id
required
string (ExternalOrderID) <= 255 characters

External purchase order ID.

This is intended to be used to map fulfillment orders to external customer orders.

Any external order ID must be unique!

currency
required
string

The ISO 4217 alphabetic code of the currency that will be paid by the customer.

Must be "USD" for now.

items
required
Array of objects (OrderItemSubmit) non-empty
shipping
required
object (ShippingInfo)

Responses

201

A reference to the submitted order

400

An error indicating where the order request was invalid

default

An unexpected error occurred

post /orders

Staging server

https://staging-api.spod.com//orders

Production server

https://api.spod.com//orders

Request samples

application/json
Copy
Expand all Collapse all
{
  • "external-order-id": "84681638-388c-4c58-8b49-325ffed37928",
  • "currency": "USD",
  • "items":
    [
    ],
  • "shipping":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{}

Retrieve a list of your submitted orders

Retrieve a list of your submitted orders

Authorizations:
oauth2 (industrial-fulfillment.read)
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

The maximum number of orders to return

offset
integer >= 0
Default: 0

Total offset in number of orders counted from the first page.

The offset starts at zero.

Example: To fetch results 20 to 30, use query parameters limit=10&offset=20

updated-since
string <date-time> (DateRFC3339)
Default: "1970-01-01T00:00:00+00:00"
Example: "2019-02-28T16:29:34+01:00"

Selects only orders updated at or after the given date (RFC3339).

The date check is inclusive, i.e. orders updated exactly on the given date are included.

Example: 2019-02-28T16:29:34+01:00

created-since
string <date-time> (DateRFC3339)
Default: "1970-01-01T00:00:00+00:00"
Example: "2019-02-28T16:29:34+01:00"

Selects only orders created at or after the given date (RFC3339).

The date check is inclusive, i.e. orders created exactly on the given date are included.

Example: 2019-02-28T16:29:34+01:00

state
string (OrderState)
Enum:"acknowledged" "confirmed" "sent" "failed" "canceled"
Example: "acknowledged"

Selects only orders with the given state, e.g. ?state=failed.

Responses

200

A list of orders submitted

default

An unexpected error occurred

get /orders

Staging server

https://staging-api.spod.com//orders

Production server

https://api.spod.com//orders

Request samples

Copy
curl --header 'User-Agent: my-api-client/v1.0' --header 'Authorization: Bearer <jwt-token>' https://api.spod.com/orders?updated-since='2019-02-28T15:15:26+01:00'&limit=10&offset=30

Response samples

application/json
Copy
Expand all Collapse all
{}

Details of a specific order

Details of a specific order

Authorizations:
oauth2 (industrial-fulfillment.read)
path Parameters
external-order-id
required
string (ExternalOrderID) <= 255 characters
Example: "84681638-388c-4c58-8b49-325ffed37928"

The external-order-id that you specified when creating the order.

Responses

200

Detailed order response

404

Order not found

default

An unexpected error occurred

get /orders/{external-order-id}

Staging server

https://staging-api.spod.com//orders/{external-order-id}

Production server

https://api.spod.com//orders/{external-order-id}

Request samples

Copy
curl --header 'User-Agent: my-api-client/v1.0' --header 'Authorization: Bearer <jwt-token>' https://api.spod.com/orders/1

Response samples

application/json
Copy
Expand all Collapse all
{}

Cancel an order

Attempts to cancel an order. It is not possible to cancel orders that have already been sent, or are already in production internally.

Authorizations:
oauth2 (industrial-fulfillment.read)
path Parameters
external-order-id
required
string (ExternalOrderID) <= 255 characters
Example: "84681638-388c-4c58-8b49-325ffed37928"

The external-order-id that you specified when creating the order.

Responses

200

Order has been canceled

400

Order could not be canceled

500

Order could not be canceled because an internal error occurred

post /orders/{external-order-id}/cancel

Staging server

https://staging-api.spod.com//orders/{external-order-id}/cancel

Production server

https://api.spod.com//orders/{external-order-id}/cancel

Response samples

application/json
Copy
Expand all Collapse all
{
  • "state": "acknowledged"
}

Product Types

Product types are used together with designs to define products in an order request. When creating a product a specific product type must be selected by its stock-keeping-unit ID that defines the basic product type (e.g. a T-Shirt), its size and appearance (e.g. black).

List available product types

List available product types

Authorizations:
oauth2 (industrial-fulfillment.read)

Responses

200

A list of available product types

default

An unexpected error occurred

get /product-types

Staging server

https://staging-api.spod.com//product-types

Production server

https://api.spod.com//product-types

Request samples

Copy
curl --header 'User-Agent: my-api-client/v1.0' --header 'Authorization: Bearer <jwt-token>' https://api.spod.com/product-types

Response samples

application/json
Copy
Expand all Collapse all
[]

Details of a specific product type

Details of a specific product type

Authorizations:
oauth2 (industrial-fulfillment.read)
path Parameters
product-type-id
required
string

ID of the product type

Responses

200

Details of the product type

404

Product Type not found

default

An unexpected error occured

get /product-types/{product-type-id}

Staging server

https://staging-api.spod.com//product-types/{product-type-id}

Production server

https://api.spod.com//product-types/{product-type-id}

Request samples

Copy
curl --header 'User-Agent: my-api-client/v1.0' --header 'Authorization: Bearer <jwt-token>' https://api.spod.com/product-types/812

Response samples

application/json
Copy
Expand all Collapse all
{}

Service Information

Service information provices basic details about the API, e.g. what version is running, where to find the documentation and who to contact in case of a failure.

API Documentation

Serves this API Documentation

Responses

200

This API documentation

default

An unexpected error occurred

get /docs

Staging server

https://staging-api.spod.com//docs

Production server

https://api.spod.com//docs

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "string",
  • "trace-id": "bba81b5e-6906-4594-bf87-b612c23bc1e0",
  • "retryable": true
}

Meta information about the API

Meta information about the API.

This resource can be used as a status check for the API.

Responses

200

Meta information about the API

default

An unexpected error occurred

get /

Staging server

https://staging-api.spod.com//

Production server

https://api.spod.com//

Request samples

Copy
curl --header 'User-Agent: my-api-client/v1.0' https://api.spod.com/

Response samples

application/json
Copy
Expand all Collapse all
{}

Shipping Countries

List available shipping countries

List available shipping countries

Authorizations:
oauth2 (industrial-fulfillment.read)

Responses

200

A list of available shipping countries

default

An unexpected error occurred

get /shipping-countries

Staging server

https://staging-api.spod.com//shipping-countries

Production server

https://api.spod.com//shipping-countries

Request samples

Copy
curl --header 'User-Agent: my-api-client/v1.0' --header 'Authorization: Bearer <jwt-token>' https://api.spod.com/shipping-countries

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]