How Can I Use the Full Transaction Import Rest API?

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 various system categories (ex: revenue)
  • Step 3 - Import transactions by submitting CSV content while referencing mappings from step 2

Typically, you will only perform step 1 and 2 once, but will repeat step 3 each time you want to import additional rows of data.

Step 1 - Get Your API Key
To obtain your API key:
  • Login to your workspace
  • On the left pane, click on "Account > My Profile"
  • Click on the "Security" tab (if needed)
  • Copy the API key

Step 2 - Prepare For Import
To prepare for import:
  • Prepare a POST call to https://salescookie.com/app/Api/PrepareImport
  • Set HTTP header X-ApiKey to your API key (step 1)
  • Set HTTP header X-DataSource to your data source's name (ex: "My ERP")
  • Submit XML as POST content to describe your fields and their mappings, such as (see mapping reference below):
    • <Mappings>
      • <TransactionDateField><FieldName>Closed Date</FieldName></TransactionDateField>
      • <OrderIdField><FieldName>Opportunity ID</FieldName></OrderIdField>
      • <CreditToUserField><FieldName>Sales Rep</FieldName></CreditToUserField>
      • <RevenueField><FieldName>Total Revenue</FieldName <IncludesCurrency>true</IncludesCurrency></RevenueField>
    • </Mappings>
  • Retrieve the response as a string - this is your transaction batch ID to use in step 3
    • Ex: "19ae9ab6-e6c1-4525-8a67-6e0e5aaf6682"

In step 3, you will upload CSV content with several fields to create transactions. All of your CSV fields must be mapped in step 2. Also, consider storing and re-using the same transaction batch ID when possible. For example, if you will keep uploading CSV content with the same fields, re-use the same transaction batch ID.

Step 3 - Import Transactions
To import transactions:
  • Prepare a POST call to https://salescookie.com/app/Api/ImportData
  • Set HTTP header X-ApiKey to your API key
  • Set HTTP header X-TransactionBatchId to your transaction batch ID (see step 2)
  • Submit CSV data as POST content, such as:
    • Closed Date,Opportunity ID,Sales Rep,Total Revenue
    • 2019-01-01,ID-1234,John Doe,$123.45
    • 2019-01-02,ID-1235,Jane Doe,$567.89

Always include headers in your posted CSV content. Also, your headers should be in the same order as for mappings specified in step 2. Finally, CSV header names should match field names specified in step 2.

Sample Code
The following samples show how to make calls (using C#) for a given API key, mapping XML and CSV content (see above for example of XML and CSV content).

// Prepare For Import
string url = "https://salescookie.com/app/Api/PrepareImport";
WebClient webClient = new WebClient();
webClient.Headers.Add("X-ApiKey", apiKey);
webClient.Headers.Add("X-DataSource", "My ERP");
string transactionBatchId = webClient.UploadString(url, mappingXml); // POST

// Import Transactions
string url = "https://salescookie.com/app/Api/ImportData";
WebClient webClient = new WebClient();
webClient.Headers.Add("X-ApiKey", apiKey);
webClient.Headers.Add("X-TransactionBatchId", transactionBatchId);
webClient.UploadString(url, csvContent); // POST

Field Mapping Reference
If you are not sure how to map fields to different system categories, you can use the web interface to determine which mappings make sense:
  • Login to your workspace
  • On the left pane, click on "Transactions > Add Transactions"
  • Select CSV as a data source and upload your CSV
  • Review mappings

Any field present in your posted CSV content must be mapped to one of the following categories. These are the XML node names to use to map fields:
  • <OrderIdField> - map this field to the "Order ID" category
    • You can only map 1 field to this category
  • <TransactionDateField> - map this field to the "Transaction Date" category
    • You can only map 1 field to this category
  • <CustomerNameField> - map this field to the "Customer" category
  • <CreditToUserField> - map this field to the "Owner / Sold By" category
  • <CreditToTeamField> - map this field to the "Territory / Team" category
  • <ProductNameField> - map this field to the "Product / Service" category
  • <EventNameField> - map this field to the "Transaction Type" category
  • <CurrencySymbolField> - map this field to the "Currency" category
  • <OrderQuantityField> - map this field to the "Order Quantity / Units" category
  • <RevenueField> - map this field to the "Transaction Revenue" category
    • Include a child node called <IncludesCurrency> whose value should be true or false
    • Include a child node called <IncludesTaxes> whose value should be true or false
  • <ProfitField> - map this field to the "Transaction Profit" category
    • Include a child node called <IncludesCurrency> whose value should be true or false
    • Include a child node called <IncludesTaxes> whose value should be true or false
  • <TaxField> - map this field to the "Taxes" category
    • Include a child node called <IncludesCurrency> whose value should be true or false
    • Include a child node called <IsPercentage> whose value should be true or false
  • <PricePerUnitField> - map this field to the "Price / Unit" category
    • Include a child node called <IncludesCurrency> whose value should be true or false
    • Include a child node called <PricePerUnitCategory> whose value should be Paid, List, Cost, Profit, or Taxes
  • <OtherField> - map this field to the "Other - Import" category
    • Include a child node called <OtherMappingCategory> whose value should be Text, Date, or Numeric 
  • <NoImportField> - map this field to the "Other - Do Not Import" category

Common Errors
Errors are reported using HTTP 500 errors, with the response content containing a more detailed description:
  • General Errors
    • Missing API key - you did not specify an X-ApiKey HTTP header
    • Invalid API key - your specified X-ApiKey HTTP header is incorrect
  • Step 2 Errors
    • Missing data source - you did not specify an X-DataSource HTTP header
    • Missing XML content - you did not specify any XML mapping content
    • Invalid XML content - your XML mapping content is malformed (not XML)
    • Invalid XML node '<Name>' - your XML mapping uses incorrect mapping XML
    • No XML mappings specified - your XML mapping does not have any field mapped
  • Step 3 Errors
    • Missing transaction batch ID - you did not specify an X-TransactionBatchId HTTP header
    • Invalid transaction batch ID - your X-TransactionBatchId data is malformed (not a GUID)
    • Invalid transaction batch ID (deleted?) - your X-TransactionBatchId data was invalidated
      • You previously completed step 2, but no data was ever imported several hours after obtaining your new transaction batch ID, so it was garbage-collected
      • You previously completed step 2, and also imported some data - however, all associated transactions were deleted, so it was garbage-collected
    • Missing CSV content - you did not specify any CSV content (step 3).

Updating Transactions
Step 3 is typically used to create transactions. However, you can also use step 3 to update existing transactions (i.e. transactions you previously imported).

To update transactions however, each transaction must have a unique ID:
  • In step 2, map one field to category "OrderIdField"
  • In step 3, ensure your CSV content specifies the correct unique ID

That's it - the system will handle your import as a create or update depending on whether it can find a matching unique ID.

    • Related Articles

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

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

    • How Can I Programmatically Import Sales Transactions?

      For non-programmatic import options, click here. Three options are available: You can use a Web Endpoint. Using this model, you deploy a web page, from which we securely pull transaction data. We will query your web page at least every hour. You can ...

    • How Can I Import Transactions?

      For programmatic import options, click here. You can use the following methods to add transactions: Manually or automatically from CSV files Manually upload CSV files containing sales transactions Automatically by having us fetch CSV files from FTP ...