Stitch Labs Integrations API

The Stitch Labs Integrations API is a RESTful API consisting of a set of JSON-compliant endponts designed to provide simplified communication between Stitch and other platforms.This initial release focuses on fulfillment, and supercedes the Fulfillment API, which will be deprecated. The Fulfillment API endpoints will continue to be supported for now, and the official sunset date will be announced once determined.

Access to the Integrations API endpoints is restricted, Reach out to our API team to request API access.

Please note that Stitch accounts must have both the Multi-warehousing and Third-Party Stock Control options enabled for these endpoints to be available. Click here for more information on these settings

Once access is granted, generating an access token for a Stitch account will create a custom channel and warehouse linked to that token. An API client with integration permissions can only authenticate once per account, to avoid the creation of duplicate channels and warehouses.

Authentication

Terminology

Apps connect to the Stitch Labs Integrations API using OAuth 2.0, the standard used by most APIs for authenticating and authorizing users. We highly suggest you use an OAuth library/wrapper to simplify the process of authenticating. If you are building this out yourself the following walkthrough will show you how to authenticate a user.

Before jumping into the authorization process, let’s go over some of the terms.

Client - Any application that would like access to a shop’s data. A user (usually the shop’s owner) must grant permission before the client can access any data

API - Stitch Labs Integrations API. This is the place where the client can view and modify a Stitch Labs Account’s data

User - A Stitch Labs Admin user. This is an admin user for the account giving permission to a client to access their shop’s data through the API

Access Token - If the user authorizes your client’s request for access, Stitch will return an Access Token which is used to sign API requests. This is a permanent API access token that can be used to access the user’s Stitch data as long as the client is authorized.

Client ID - The unique shared secret for your client application

Client Secret - OAuth2, uses the client secret mechanism as a means of authorizing a client, the software requesting an access token. This secret proves to the authentication server that the client app is authorized to make a request on behalf of the user. The secret can be retrieved from your API Credentials settings in the developer portal.

Redirect URL - The location to redirect the user after they authorize the client. The host of this URL must be identical to the host of the Application Callback URL. The redirect_uri must be identical the REDIRECT URL specified in the API Credentials settings.

State - A query parameter that the client includes in the request and the Authorization server returns as a parameter of the response unmodified. This field is optional but allows for additional protections from Cross Site Request Forgery (XRSF)


Fulfillment Workflow

The fulfillment workflow allows 3PLs and other logistic providers to integrate easily with Stitch for processing fulfillments and providing stock information. There are three sets of endpoints, follow the links for details on the endpoints and related workflows:

Products >>

The products endpoints are used to post a list of products to Stitch.

Fulfillments >>

Fulfillments provide the details of what needs to be shipped and where.

Shipments >>

Shipments represent the items that have shipped, including tracking information.

General Fulfillment Workflow

To get started, a list of the products carried and current stock levels is posted to Stitch. Once in Stitch, only updates to stock levels need to be pushed up. This information is used to update the fulfillment warehouse in Stitch. The total on-hand stock can only be updated through the API. These values can not be edited directly in Stitch, though Stitch will still use internal logic to calculate availability. This ensures that the stock levels in Stitch stay in sync with the warehouse.

Fulfillments are triggered in two ways. Most are automatically triggered for incoming orders from an integrated sales channel. Also, fulfillments can be triggered manually from the Order Details. Once triggered, Stitch checks several criteria before a fulfillment can be initialized.

  • The order is assigned to a fulfillment warehouse.
  • There is enough stock available in the assigned warehouse to fulfill the order.
  • The shipping address is populated.
  • Criteria for invoicing and payment status can be set in Stitch, but are not required.

Once the fulfillment is initialized, the standard API workflow is:

  1. GET the list of open fulfillments from the /fulfillments endpoint.
  2. GET the line items for the fulfillments. Bundle SKUs (kits) will not appear as line items on fulfillments, the component SKUs will appear in the correct quantities.*
  3. POST shipments for the line items on each fulfillment, including a timestamp for "shipped_at"
  4. Once all line items are related to a shipment, the fulfillment is considered complete and will no longer be returned with the fulfillments list.

At any point during the workflow, the fulfillment status can be updated. This is not required, but strongly recommended for visibility. The status field can be set to any string, which will be displayed in Stitch.

*Requires the "Split Bundles into Components" option enabled in the Stitch account settings.

Authentication Process

Navigate to the API Credentials area of the Developer Portal to set your Redirect URL. The Redirect URL is the URL within your application that will receive the OAuth2 credentials.

Base URL: https://api-pub.stitchlabs.com
Authorization URL: https://api-pub.stitchlabs.com/authorize
Access Token URL: https://api-pub.stitchlabs.com/oauth/token

Step 1: Ask User for API Access Permission

The first step of process is to prompt the user for authorization. To display the prompt, redirect the user to authenticate through the Authorization URL:

https://api-pub.stitchlabs.com/authorize?response_type=code&scope=&client_id={api_key}&redirect_uri={redirect_uri}&state={state}

Step 2: Request a OAuth Token

After the successfully authenticating in the prompt Stitch will respond with an authorization code to be used in the subsequent token request to the Access Token URL

POST https://api-pub.stitchlabs.com/oauth/token?client_id={api_key}&client_secret={client_secret}&code={authorization_code}&grant_type=authorization_code&redirect_uri={redirect_uri}&scope=

Please Note: The scope parameter is now required in the authorization request (even if it's empty)

Step 3: Making authenticated requests

Once the client has obtained an API access token from the previous step, it can used to make authenticated requests to the API. Authenticated requests are signed with a header pair of access_token: {access_token} where {access_token} is replaced with the permanent token for the user.

Refreshing User OAuth Tokens

Once retrieved you can use tokens indefinitely in your application without re-authenticating. Stitch is not currently expiring/revoking tokens based on time.

Rate Limiting

Depending on your subscription plan, API requests are throttled by the server at different thresholds. If Stitch Public API endpoints receive too many requests associated with the same application or access token in a short time window, they might respond with a 429 Too Many Requests error. If this occurs, try your request again at a later time. Your application should take this into account and throttle requests locally as well.

Postman

Overview

Postman is a powerful API testing and development suite used to help developers explore our Public API. It also provides a fast way to generate a token for testing and development.

Installing Postman and Collections

Step 1: Download Postman

Download and Install the Postman Packaged Chrome Application

Step 2: Retrieve a Token

  1. Navigate to the API Credentials area of the Developer Portal to set your Redirect URL to https://www.getpostman.com/oauth2/callback
  2. Select the OAuth 2.0 Tab in Postman and paste in your:
    Authorization URL
    Access Token URL
    Client ID
    Client Secret
  3. Click Get Access Token
  4. Authenticate / Approve Access with Stitch in the popup window
  5. Name and Save the retrieved token

Step 3: Making Authenticated Requests

  1. Select an endpoint from the provided Collections
  2. Click to OAuth 2.0 tab to indicate you are making a OAuth POST
  3. Copy your access token into an access_token: {access_token} header parameter
  4. Send the POST request

Postman Environment Variables

The easiest way to sign API requests with your token is by defining an environment variable in Postman to store your retrieved oAuth token.

  1. Select Manage Environments from the Environment Dropdown

  2. Add a new environment

  3. Add a key for “token” with a value of your token

With this environment selected you should be able to make signed requests without needing to update your headers.