Shippo integration summary

Stitch’s Shippo integration replicates data using the Shippo API. Refer to the Schema section for a list of objects available for replication.

Shippo feature snapshot

A high-level look at Stitch's Shippo integration, including release status, useful links, and the features supported in Stitch.

STITCH
Release Status

Released

 Supported By

Singer Community
Stitch Plan

Free

 Singer GitHub Repository

Shippo Repository

DATA SELECTION
Table Selection

Unsupported

 Column Selection

Unsupported
REPLICATION SETTINGS
Anchor Scheduling

Unsupported

 Advanced Scheduling

Unsupported
Table-level Reset

Unsupported

 Configurable Replication Methods

Unsupported
TRANSPARENCY
Extraction Logs

Unsupported

 Loading Reports

Supported

Connecting Shippo

Step 1: Retrieve your Shippo API token

  1. Sign into your Shippo account.
  2. In the left nav tab, click API.

  3. Locate the API LIve Token field in the Tokens section:

    Shippo API token.

    Leave this page open for now - you’ll need it to complete the setup.

Step 2: Add Shippo as a Stitch data source

  1. Sign into your Stitch account.

  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the Shippo icon.

  4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch Shippo” would create a schema called stitch_shippo in the destination. Note: Schema names cannot be changed after you save the integration.

  5. In the Shippo Token field, paste your Shippo API Live token.

Step 3: Define the historical sync

The Sync Historical Data setting will define the starting date for your Shippo integration. This means that data equal to or newer than this date will be replicated to your data warehouse.

Change this setting if you want to replicate data beyond Shippo’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.

Step 4: Create a replication schedule

In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

Shippo integrations support the following replication scheduling methods:

To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.

Initial and historical replication jobs

After you finish setting up Shippo, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.

Shippo table schemas

addresses

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

object_updated
Primary Key :

object_id

 API endpoint :

listAllAddresses

The addresses table contains info about address objects. These are used to create shipments, obtain rates, and print labels.

addresses table schema

object_id
STRING

The address object ID.

Reference:

object_updated
DATE-TIME

The last time the address was updated.

object_state
STRING

The state of the address. Possible values include VALID, INVALID, and INCOMPLETE.

object_purpose
STRING

Indicates if the address can be used to purchase labels or only obtain rates. Possible values are QUOTE and PURCHASE.

object_source
STRING

The source of the address. Possible values are FULLY_ENTERED, PARTIALLY_ENTERED, and VALIDATOR.

object_created
DATE-TIME

The time the address was created.

object_owner
STRING

The username of the user who created the address.

name
STRING

The first and last name of the addressee.

company
STRING

The company name associated with the address.

street1
STRING

The first street line of the address.

street2
STRING

The second street line of the address.

city
STRING

The name of the city contained in the address.

state
STRING

The state of the address. State values are only required for United States and Canada. Ex: PA

zip
STRING

The postal code of the address.

country
STRING

The address’s country code. Ex: US

phone
STRING

The phone number associated with the address.

email
STRING

The email address of the contact person.

is_residential
BOOLEAN

Indicates if the address is a residential address.

metadata
STRING

Additional information about the address.

test
BOOLEAN

Indicates if the address was created in test mode.

messages
ARRAY

Details about messages associated with the address.

Click to expand messages

code
STRING

The ID of the message. This may not always be available.

source
STRING

The source of the message. Ex: USPS

text
STRING

The text of the message.
addresses (table), messages (attribute)

parcels

Replication Method :

Key-based Incremental

 Replication Key :

object_updated
Primary Key :

object_id

 API endpoint :

listAllParcels

The parcels table contains info about parcel objects. Parcels are used to create shipments, obtain rates, and print labels.

parcels table schema

object_id
STRING

The parcel ID.

Reference:

object_updated
DATE-TIME

The last time the parcel was updated.

object_state
STRING

The state of the parcel. Ex: VALID

object_created
DATE-TIME

The time the parcel was created.

object_owner
STRING

The username of the user who created the parcel.

template
STRING

This is the template defined for the parcel. A parcel template is a predefined package used by one or multiple carriers.

Click the link in the left column for more info about possible values in Shippo’s documentation.

length
STRING

The length of the parcel.

width
STRING

The width of the parcel.

height
STRING

The height of the parcel.

distance_unit
STRING

The unit used for length, width, and height. Possible values are:

  • cm
  • in
  • ft
  • mm
  • m
  • yd

weight
STRING

The weight of the parcel.

mass_unit
STRING

The unit used for weight. Possible values include:

  • g
  • oz
  • lb
  • kg

metadata
STRING

Additional information about the parcel.

extra
OBJECT

Optional extra services requested for each parcel in a multi-parcel shipment.

Click the link in the left column for more info about possible values in Shippo’s documentation.

test
BOOLEAN

Indicates if the parcel was created in test mode.

refunds

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

object_updated
Primary Key :

object_id

 API endpoint :

listAllRefunds

The refunds table contains info about refunds, which are reimbursements for successfully created but unused transactions.

Refund processing time and data discrepancies

If the data in this table doesn’t look like you’d expect it to, keep in mind that refunds can take up to 14 days to be processed.

refunds table schema

object_id
STRING

The refund ID.

object_updated
DATE-TIME

The time the refund was last updated.

object_created
DATE-TIME

The time the refund was created.

object_owner
STRING

The username of the user who created the refund.

transaction
STRING

The ID of the transaction to be refunded.

Reference:

test
BOOLEAN

Indicates if the refund was created in test mode.

shipments

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

object_updated
Primary Key :

object_id

 API endpoint :

listAllShipments

The shipments table contains info about shipment objects. Shipment objects are made up of to and from addresses and the parcel to be shipped.

shipments table schema

object_id
STRING

The shipment ID.

object_updated
DATE-TIME

The last time the shipment was updated.

object_state
STRING

The state of the shipment. Possible values are VALID, INCOMPLETE, and INVALID.

object_purpose
STRING

Indicates whether a shipment can be used to purchase labels or only obtain quote rates. Possible values are QUOTE and PURCHASE.

object_created
DATE-TIME

The time the shipment was created.

object_owner
STRING

The username of the user who created the shipment.

object_from
STRING

The ID of the address that should be used as the sender address.

Reference:

object_to
STRING

The ID of the address that should be used as the recipient address.

Reference:

object_return
STRING

The ID of the address where the shipment will be sent back if it isn’t delivered. If this field is not set, shipments will be returned to the address in the object_from field.

Reference:

object_parcel
STRING

The ID of the parcel to be shipped.

Reference:

submission-date
DATE-TIME

The date the shipment will be tendered to the carrier.

insurance_amount
STRING

The total parcel value to be insured.

insurance_currency
STRING

The currency used for insurance_amount.

extra
OBJECT

customs_declaration
STRING

The ID of the customs declarations object for an international shipment.

reference1
STRING

Optional text to be printed on the shipping label.

reference2
STRING

Optional text to be printed on the shipping label.

rates_url
STRING

The URL of the rates list for the given shipment.

rates_list
ARRAY

Values of available rates.

Click to expand rates_list

value
STRING

The available rate value.
shipments (table), rates_list (attribute)

carrier_accounts
ARRAY

IDs of the carrier accounts to be used for getting shipping rates for the shipment.

Click to expand carrier_accounts

value
STRING

The carrier ID.
shipments (table), carrier_accounts (attribute)

metadata
STRING

Additional information about the shipment.

test
BOOLEAN

Indicates if the shipment was created in test mode.

messages
ARRAY

Details about messages associated with the shipment.

Click to expand messages

code
STRING

The ID of the message. This may not always be available.

source
STRING

The source of the message. Ex: USPS

text
STRING

The text of the message.
shipments (table), messages (attribute)

transactions

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :
Primary Key :

object_id

 API endpoint :

listAllTransactions

The transactions table contains info about transactions, which are the purchases of shipping labels from a shipping provider for a specific service.

transactions table schema

object_id
STRING

The transaction ID.

Reference:

object_updated
DATE-TIME

The time the transaction was last updated.

object_state
STRING

Indicates the validity of the transaction based on the given data, regardless of what the carrier returns.

Possible values include VALID and INVALID.

object_status
STRING

The status of the transaction. Possible values:

  • WAITING
  • QUEUED
  • SUCCESS
  • ERROR
  • REFUNDED
  • REFUNDPENDING
  • REFUNDREJECTED

object_created
DATE-TIME

The time the transaction was created.

object_owner
STRING

The username of the user who created the transaction.

test
BOOLEAN

Indicates if the transaction was created in test mode.

rate
STRING

The ID of the rate object for which a label has to be obtained.

tracking_number
STRING

The carrier-specific tracking number that can be used to track the shipment. A value will only be returned if:

  • The rate is for a trackable shipment, and
  • The transaction has been processed successfully.

tracking_status
OBJECT

The latest tracking information for the shipment.

Click to expand tracking_status

value
STRING

The tracking status.
transactions (table), tracking_status (attribute)

tracking_history
ARRAY

A list of tracking events for the shipment the transaction is associated with.

tracking_url_provider
STRING

The URL used to track the item on the carrier-provided tracking website.

label_url
STRING

The URL for the label in the format defined in the account settings.

commercial_invoice_url
STRING

The URL for the commercial invoice for this transaction as a PDF. Values are only returned if:

  • The transaction has been processed successfully, and
  • The shipment is international

metadata
STRING

Additional information about the transaction.

messages
ARRAY

Details about messages associated with the transaction.

Click to expand messages

code
STRING

The ID of the message. This may not always be available.

source
STRING

The source of the message.

text
STRING

The text of the message.
transactions (table), messages (attribute)
Related Troubleshooting
Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.