How Can I Use The CSV Upload API?

How Can I Use The CSV Upload API?


This article is about CSV transaction upload API. This is by far the easiest way to upload sales transactions, and it is also blazing fast. About 1-3 lines of code are required to upload transactions. All you need to do is prepare a CSV file and then POST it via HTTP. Click here for more options.

Automating Transaction Uploads
To automatically import transaction data, follow these 3 steps:
  • Step 1 - Upload Sample CSV Data
  • Step 2 - Get Upload URL
  • Step 3 - Automatically Upload CSV Data

Step 1 - Upload Sample CSV Data
To import sample CSV data:
  • Login to your workspace
  • On the left pane, click on "Transactions > Add Transactions"
  • Manually upload a CSV file with sample sales data

Step 2 - Get Upload URL
  • One the upload is complete, click on "Transactions > All Transactions"
  • Click on any of your uploaded transactions
  • Click on the "Metadata" tab
  • Copy the upload URL



Step 3 - Automatically Upload CSV Data
You now have the ability to programmatically upload transaction CSV data. First, make sure CSV data you upload programmatically has the exact same format as the CSV file used in step 1 (same header names, same field order, no extra spaces in headers, etc.). 

To upload CSV data, simply POST CSV file content to your URL which should look like this:

The configuration hash represents the expected format while the API key grants access.

That's it - your programmatically uploaded CSV data is converted to transactions. We will accept posted data immediately, and start ingesting in the background.

Recommendations
Here are some tips to make the best use of the upload API:
  • Upload data at a reasonable cadence
    • For example, upload daily or every few hours (NOT each time a single record is updated)
    • Excessive uploads will result in throttling errors
  • Upload data using reasonable batch sizes
    • For example, upload few MBs at a time (NOT 100 MBs)
    • Excessive uploads will result in throttling errors
  • Use a reasonable HTTP timeout
    • Please ensure your HTTP POST uses a sufficient timeout (ex: 30 seconds)
    • Your timeout should be sufficient to allow us to accept sent data (this data will be processed in the background)
    • Note that there is often a separate connection timeout vs. request timeout so you may need to specify both
  • Don't forget to include headers in each upload
    • Remember to do this if you batch CSV data
  • Implement simple retry logic such as exponential back-off
    • Although rare, 500 errors may happen due to network timeouts
    • Note that we accept posted data immediately, and start ingesting in the background
    • Issue monitoring alerts if the upload fails after all retries have been exhausted
  • Consider sending all records created OR updated in the last N days
    • This means that the same records will be pushed repeatedly
    • However, this is quite harmless, and it keeps your upload logic simple and robust
    • For example, if your upload process stops running for 2 days, the next upload will "catch up"
    • It also means you don't need to track precisely what has been uploaded / not uploaded  
  • Make sure your CSV conforms 100% to the agreed upon format
    • Any change to the data (ex: new fields, different order) requires a new upload URL
  • Normalize dates and numbers within your CSV
    • Please refer to the information below

Curl Command Line

Windows PowerShell

Postman
  • Use the binary option to POST file content "as is"


Dates Formatting
We strongly recommend using the YYYY-MM-DDThh:mm:ss ISO format (ex: "2021-01-13T19:34:56") for all dates in your CSV. This eliminates all possible confusion as to whether months or days are specified first (this varies from country to country). If you have dates such as 2021-01-13, use "2021-01-13T00:00:00".

Also, each workspace has a primary time zone (under Settings > Time Zone). This time zone is of great importance in terms of selecting appropriate transactions when calculating commissions for a given time period. Your workspace time zone is used to determine exact cutoff times, and helps us handle special situations such as daylight saving changes (more info).

Therefore, all dates in your CSV should either:
  • Be specified in the time zone of your workspace          OR
  • Be specified as UTC dates with the "Z" ISO indicator

For example, if your workspace uses the Pacific time zone, and you specify a date of "2021-01-13T19:34:56", it will be assumed to be in Pacific time (so make sure this is true). However, if you specify a date of "2021-01-13T07:34:56Z", it is understood to be in UTC due to the "Z" ISO indicator. Both representations are equally valid.

Number Formatting
All numbers should be formatted using the US convention. For example, a value of one thousand and 33 cents should be represented as "1000.33" or "1,000.33" in your CSV (for example, not "1.000,33" - a format used in some EU countries).

CSV Format Changes
If your CSV format changes, you must generate a new upload URL. Perform the same steps 1-2 as previously.

    • Related Articles

    • How Can I Use The Transaction Import API?

      The data import API allows you to create (or update) sales transactions within Sales Cookie using HTTP requests. Three options are available to import sales transactions using an API: Use the CSV Upload API (easiest) Manually upload a sample CSV file ...

    • How Can I Use the Full Transaction Import Rest API?

      This article is about the full transaction import REST API. Click here for more options. Importing Sales Transactions To import transaction data, follow these 3 steps: Step 1 - Get your API key Step 2 - Prepare for import by mapping your fields to ...

    • How Can I Use the Simplified Transaction Import Rest API?

      This article is about the simplified transaction import REST API. Click here for more options. Importing Sales Transactions To import transaction data, follow these 2 steps: Step 1 - Get your API key Step 2 - Import transactions by making a POST call ...

    • Can I Use Restricted Keys For Stripe Access?

      When you add a Stripe connection to your workspace, you can choose to use a restricted key. This allows you to safeguard your Stripe environment by: Limiting access to read-only mode Limiting access to those entities required to calculate commissions ...

    • How Can I Use The Zapier Integration?

      The Zapier integration provides access to: A "Create Transaction" Action This allows you to add or update sales transactions within Sales Cookie. For example, you could create a Zap which calls this action when a new invoice or opportunity is created ...