Release Status Released Supported By Singer community
Availability Free Status Page Shippo Status Page
Default Historical Sync 1 year Default Replication Frequency 30 minutes
Whitelisting Unsupported Destination Incompatibilities None

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 sync data beyond Shippo’s default setting of 1 year. For a detailed look at historical syncs, 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.

Stitch offers two methods of creating a replication schedule:

  • Replication Frequency: This method requires selecting the interval you want replication to run for the integration. Start times of replication jobs are based on the start time and duration of the previous job. Refer to the Replication Frequency documentation for more information and examples.
  • Anchor scheduling: Based on the Replication Frequency, or interval, you select, this method “anchors” the start times of this integration’s replication jobs to a time you select to create a predictable schedule. Anchor scheduling is a combination of the Anchor Time and Replication Frequency settings, which must both be defined to use this method. Additionally, note that:

    • A Replication Frequency of at least one hour is required to use anchor scheduling.
    • An initial replication job may not begin immediately after saving the integration, depending on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.

To help prevent overages, 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

Replication Method: Key-based Incremental Replication Key : object_updated
Primary Key : object_id API Endpoint: listAllAddresses

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

object_id
STRING

The address object ID.

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

Details about messages associated with the address.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named addresses__messages and may contain the following attributes:

_sdc_source_key_object_id
STRING

The address object ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

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.


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.

object_id
STRING

The parcel ID.

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.

test
BOOLEAN

Indicates if the parcel was created in test mode.


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 & 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.

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.

test
BOOLEAN

Indicates if the refund was created in test mode.


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.

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.

object_to
STRING

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

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.

object_parcel
STRING

The ID of the parcel to be shipped.

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.

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

Values of available rates.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named shipments__rates_list and may contain the following attributes:

_sdc_source_key_object_id
STRING

The shipment ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The available rate value.

carrier_accounts

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

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named shipments__carrier_accounts and may contain the following attributes:

_sdc_source_key_object_id
STRING

The shipment ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The carrier ID.

metadata
STRING

Additional information about the shipment.

test
BOOLEAN

Indicates if the shipment was created in test mode.

messages

Details about messages associated with the shipment.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named shipments__messages and may contain the following attributes:

_sdc_source_key_object_id
STRING

The shipment ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

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.


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.

object_id
STRING

The transaction ID.

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__value
STRING

The tracking status.

tracking_history

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

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named transactions__tracking_history and may contain the following attributes:

_sdc_source_key_object_id
STRING

The transaction ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

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

Details about messages associated with the transaction.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named transactions__messages and may contain the following attributes:

_sdc_source_key_object_id
STRING

The transaction ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

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.



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.