Examples
Adding a payment gateway application
Since version 9.1.0, 3dcart has offered developers the ability to integrate new payment gateway applications. To do this, the authentication methods used by the REST API are used to connect your application with merchants, and then you provide the endpoint POST URL's that 3dcart will use during the checkout and post checkout process. The steps to add a payment gateway are listed below:
Creating the application in the developer portal
- Login or register at http://devportal.3dcart.com
- Click the 'Add New' button to create a new application
- On the application Dashboard page, find the 'Payment Gateway Settings' section, as seen below:
- Check the 'Is Payment Gateway' checkbox
- Enter the information in their applicable fields:
- Gateway Checkout URL: This is the endpoint 3dcart will use for payment authorization at checkout.
- Gateway Post-Order URL: This is the endpoint that 3dcart will use for any Post order transaction (i.e. void, refund, etc.).
- Gateway Logo URL: This is the logo the merchant will see displayed in the Online Store Manager.
- Credential 1 and 2 Captions: These determine the captions that are displayed next to the fields that accept the merchants credentials (e.g username, transaction key, secret key, etc.) when they configure the payment gateway in their Online Store Manager.
Sample Gateway Application
A sample gateway application is available here. This is a sample application intended to serve as a model for any developer wanting to build an integration for a redirect payment gateway with 3dcart. The app is built in .NET MCV (C#).
Checkout Sequence Diagram
Initiating the Checkout Request
Sale Transaction Request/CheckoutRequest object
{
"type":"sale",
"orderid":123,
"invoice":"AB-12234",
"email":"123@123.com",
"billing":{
"firstname":"abc",
"lastname":"xyz",
"company":"abc",
"address":"123 abc",
"address2":"aaa",
"city":"tamarac",
"state":"FL",
"zip":"33067",
"country":"US",
"phone":"1231231212"
},
"shipping":{
"firstname":"abc",
"lastname":"xyz",
"company":"abc",
"address":"123 abc",
"address2":"aaa",
"city":"tamarac",
"state":"FL",
"zip":"33067",
"country":"US",
"phone":"1231231212"
},
"currency":"USD",
"amounttotal":12312,
"taxtotal":1000,
"shippingtotal":500,
"discount":1000,
"items":[
{
"itemid":"123abc",
"itemname":"item name 123",
"unitprice":1200,
"quantity":2
},
{
"itemid":"asd1-22",
"itemname":"item name abc",
"unitprice":2200,
"quantity":3
},
{
"itemid":"111q-azas",
"itemname":"item name xyz",
"unitprice":5,
"quantity":10
}
],
"username":"user1",
"password":"password1",
"cancelurl":"https://example-com.3dcartstores.com/checkout.asp",
"errorurl":"https://example-com.3dcartstores.com/error.asp?error=0",
"notificationurl":"https://example-com.3dcartstores.com/paymentreceive_json.asp?gw=123",
"returnurl":"https://example-com.3dcartstores.com/paymentreceive.asp?gw=123&orderid=orderid&rk=randomkey&k=md5(rk + getdomainname + getstoreid + gatewayid)",
"randomkey":"abc321123xyz",
"signature":"calculated md5(randomkey + app_privatekey + orderid + invoice + amounttotal)"
}
When a user clicks the checkout button in order to finish the order, 3dcart will send a POST request to the 'Gateway Checkout URL' you provided in the Payment Gateway Settings of your application's Dashboard. The Sale Transaction Request/CheckoutRequest json object to the right will be included in the payload of this request. Please note that the signature is a calculated md5 hash that can be used to validate requests.
Sale Transaction Request/CheckoutRequest object
| Property | Description |
|---|---|
| type | The type of transaction (i.e. sale, void, refund, etc.) |
| orderid | The unique database id of the order |
| invoice | The merchant's invoice number of the order |
| The user's email address | |
| billing | The user's billing address |
| shipping | The user's shipping address |
| currency | The merchant's configured currency |
| amounttotal | The total amount of the order |
| taxtotal | The total tax amount calculated on the order |
| shippingtotal | The total shipping amount calculated on the order |
| discount | The total discount amount calculated on the order |
| items | A collection of the items purchased |
| username | The merchant's login Credential 1 as you configured in the Payment Gateway Settings |
| password | The merchant's login Credential 2 as you configured in the Payment Gateway Settings |
| cancelurl | The URL to redirect the user if they cancel the checkout sequence |
| errorurl | The URL to redirect the user if their is an error while processing the Sale Transaction Request/CheckoutRequest |
| notificationurl | The URL to send a POST request containing the Sale Transaction Response/CheckoutResponse object |
| returnurl | The URL to redirect the user after they have completed the checkout sequence |
| randomkey | A randomly generated alphanumeric string |
| signature | A calculated md5 hash containing (in this order): the randomkey value, your payment gateway application's Private Key, orderid value, invoice value, and the amounttotal value. |
The Checkout Response
Sale Transaction Response/CheckoutResponse object
{
"paymenttoken":"abc123xyz321",
"redirecturl":"https://www.examplecheckoutpageurl.com/checkout",
"redirectmethod":"GET",
"errorcode":"abc123",
"errormessage":"error message",
"randomkey":"999azswed23xyz",
"signature":"md5(randomkey + app_privatekey + paymenttoken + redirecturl)"
}
Once you have received and validated/processed the Sale Transaction Request/CheckoutRequest object on the payment gateway side, the response to this POST request should contain the Sale Transaction Response/CheckoutResponse json object to the right.
Please note the signature field is a calculated md5 hash and the app_privatekey portion of it is your payment gateway application's Private Key from the application Dashboard in the developer portal. Additionally, the paymenttoken field can be used on your side as an extra verification, however, it is not required and can be left blank.
Once we have received and validated this response object, if the error message field is not populated, 3dcart will redirect the user to the redirecturl included in the response, using the HTTP method specified in the redirectmethod. If the payment token field was populated, it will be included as a URL query string parameter for GET requests, and as part of the body payload if it's a POST request.
If, however the errormessage field is populated, 3dcart will display the merchant's store configured error message to the user, and record the errormessage value in the order's internal comments field so the merchant can view the error message in their Online Store Manager.
Sale Transaction Response/CheckoutResponse object
| Property | Description |
|---|---|
| paymenttoken | An optional alphanumeric string |
| redirecturl | The URL that 3dcart will redirect the user to process payment |
| redirectmethod | The HTTP method of the redirect |
| errorcode | The code of any error occurring. Will be visible to merchant in the Online Store Manager. |
| errormessage | The error message of any error occurring. Will be visible to merchant in the Online Store Manager. |
| randomkey | A randomly generated alphanumeric string |
| signature | A calculated md5 hash containing (in this order): the randomkey value, your payment gateway application's Private Key, paymenttoken, and redirecturl. |
User redirected to payment gateway page
Sale Confirmation Request/CompleteOrderRequest object
{
"orderid":123,
"invoice":"AB-12234",
"amount":12312,
"approved":1,
"transactionid":"abc12345",
"errorcode":"abc123",
"errormessage":"error message",
"randomkey":"999azswed23xyz",
"signature":"md5(randomkey + app_privatekey + orderid + invoice + transactionid)"
}
Sale Confirmation Response/CompleteOrderResponse
{
"processed":1,
"errorcode":"abc123",
"errormessage":"error message"
}
At this point, the user has been redirected to your payment gateway application's checkout page in order to process their payment. Upon successfully processing payment, you will send a POST request to the 3dcart store's notificationurl, which was received in the Sale Transaction Request/CheckoutRequest object sent to the 'Gateway Checkout URL' when 3dcart initiated the checkout sequence. This request should contain the Sale Confirmation Request/CompleteOrderRequest json object seen to the right.
The response to this request will contain the Sale Confirmation Response/CompleteOrderResponse json object seen to the right. If the processed value is 0, then the errorcode and errormessage fields will be populated. The user should be redirected to the URL included in the errorurl field (replace the error query parameter in the URL with the errorcode received in the Sale Confirmation Response/CompleteOrderResponse), which was received in the Sale Transaction Request/CheckoutRequest object sent to the 'Gateway Checkout URL' when 3dcart initiated the checkout sequence.
Sale Confirmation Request/CompleteOrderRequest object
| Property | Description |
|---|---|
| orderid | The unique database ID of the order, which was sent in the initial CheckoutRequest object when 3dcart initiated the checkout process. |
| invoice | The merchant's invoice number, which was sent in the initial CheckoutRequest object when 3dcart initiated the checkout process. |
| amount | The order amount total, which was sent in the initial CheckoutRequest object when 3dcart initiated the checkout process. |
| approved | A boolean indicating approval status |
| transactionid | Your payment gateway applications unique transaction ID. |
| errorcode | The error code of any error that occurred. |
| errormessage | The error description of any error that occurred. |
| randomkey | A randomly generated alphanumeric string |
| signature | A calculated md5 hash containing (in this order): the randomkey value, your payment gateway application's Private Key, orderid, invoice, and transactionid. |
Sale Confirmation Response/CompleteOrderResponse object
| Property | Description |
|---|---|
| processed | A boolean indicating processing status |
| errorcode | The error code of any error that occurred. |
| errormessage | The error description of any error that occurred. |
Completing the order checkout sequence
If the processed value in the Sale Confirmation Response/CompleteOrderResponse json object is 1, this means 3dcart has successfully received and processed the Sale Confirmation Request/CompleteOrderRequest json object you sent and the user can be redirected back to the URL in the returnurl, which was received in the CheckoutRequest object sent to the 'Gateway Checkout URL' when 3dcart initiated the checkout sequence.
Refund Sequence Diagram
Requesting to Refund a Transaction
RefundRequest object
{
"type":"void",
"orderid":123,
"invoice":"AB-12234",
"transactionid":"abc12345",
"username":"user1",
"password":"password1",
"currency":"USD",
"amounttotal":12312,
"is_full_refund":true,
"randomkey":"abc321123xyz",
"signature":"calculated md5(randomkey + app_privatekey + orderid + invoice + transactionid)"
}
RefundResponse object
{
"approved":1,
"transactionid":"abc12345",
"errorcode":"abc123",
"errormessage":"error message",
"randomkey":"999azswed23xyz",
"signature":"md5(randomkey + app_privatekey + orderid + invoice + transactionid)"
}
When a merchant clicks the Void/Refund transaction button, 3dcart will send a POST request to the 'Gateway Post Order URL' containing the RefundRequest json object. The 'Gateway Post Order URL' was entered in the payment gateway settings of your application in the developer portal. Your application's Post Order URL will process/validate this request and respond with the RefundResponse object. 3dcart will then redirect the merchant to a page (or display a modal) that displays the results of the request/response sequence (i.e. display any success/error messages).
RefundRequest object
| Property | Description |
|---|---|
| type | The transaction type |
| orderid | The unique database id of the order |
| invoice | The merchant's invoice number |
| transactionid | The unique transaction id |
| username | The merchant's login Credential 1 as you configured in the Payment Gateway Settings |
| password | The merchant's login Credential 2 as you configured in the Payment Gateway Settings |
| amounttotal | The total amount to be refunded |
| is_full_refund | A boolean indicating if this is the whole order amount |
| randomkey | A randomly generated alphanumeric string |
| signature | A calculated md5 hash containing (in this order): the randomkey value, your payment gateway application's Private Key, orderid, invoice, and transactionid. |
RefundResponse object
| Property | Description |
|---|---|
| approved | A boolean indicating the approval status |
| transactionid | The unique transaction id for the refund |
| errorcode | The error code of any error that occurred. |
| errormessage | The error description of any error that occurred. |
| randomkey | A randomly generated alphanumeric string |
| signature | A calculated md5 hash containing (in this order): the randomkey value, your payment gateway application's Private Key, orderid, invoice, and transactionid. |
Importing orders from a 3rd party system
Warnings
Prerequisites
Importing orders
Order example 1
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
\"InvoiceNumberPrefix\": \"ABC-\",
\"InvoiceNumber\": 123456,
\"CustomerID\": 1,
\"OrderDate\": \"05/01/2019 09:49\",
\"OrderStatusID\": 4, // Most likely the Shipped status id
\"BillingFirstName\": \"John\",
\"BillingLastName\": \"Smith\",
\"BillingCompany\": \"ACME, Inc.\",
\"BillingAddress\": \"123 Main St.\",
\"BillingAddress2\": \"Suite 100\",
\"BillingCity\": \"Tamarac\",
\"BillingState\": \"FL\",
\"BillingZipCode\": \"33321\",
\"BillingCountry\": \"US\",
\"BillingPhoneNumber\": \"8008286650\",
\"BillingEmail\": \"john.smith@acme.com\",
\"BillingPaymentMethod\": \"Payment Processor\",
\"BillingOnLinePayment\": false,
\"BillingPaymentMethodID\": \"123\",
\"ShipmentList\": [
{
\"ShipmentBoxes\": 1,
\"ShipmentInternalComment\": \"Extra packing material\",
\"ShipmentOrderStatus\": 1, // Most likely the Shipped status id
\"ShipmentAddress\": \"123 Main St.\",
\"ShipmentAddress2\": \"Suite 100\",
\"ShipmentAlias\": \"Alias\",
\"ShipmentCity\": \"Tamarac\",
\"ShipmentCompany\": \"ACME, Inc.\",
\"ShipmentCost\": 10.00,
\"ShipmentCountry\": \"US\",
\"ShipmentEmail\": \"john.smith@acme.com\",
\"ShipmentFirstName\": \"John\",
\"ShipmentLastName\": \"Smith\",
\"ShipmentMethodName\": \"UPS Ground\",
\"ShipmentShippedDate\": \"05/01/2019 09:49\",
\"ShipmentPhone\": \"8008286650\",
\"ShipmentState\": \"FL\",
\"ShipmentZipCode\": \"33321\",
\"ShipmentTax\": 0.00,
\"ShipmentWeight\": 1.50,
\"ShipmentTrackingCode\": \"ABC12345678901234567890\",
\"ShipmentNumber\": 1,
}
],
\"OrderItemList\": [
{
\"CatalogID\": 123456,
\"ItemID\": \"SKU-SAMPLE\",
\"ItemQuantity\": 1,
\"ItemUnitPrice\": 9.99,
\"ItemWeight\": 2.5,
\"ItemDateAdded\": \"05/01/2019 09:49\",
}
],
\"SalesTax\": 0.60,
\"OrderAmount\": 20.59,
}");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Accept: application/json",
"SecureURL: ",
"PrivateKey: ",
"Token: "
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;
var baseAddress = new Uri("https://apirest.3dcart.com/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("accept", "application/json");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("secureurl", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("privatekey", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("token", "");
using (var content = new StringContent("{ \"InvoiceNumberPrefix\": \"ut ex\", \"InvoiceNumber\": -76055332, \"OrderID\": 7966749, \"CustomerID\": -42238041, \"OrderDate\": \"1969-08-06T11:55:32.817Z\", \"OrderStatusID\": 25219641, \"LastUpdate\": \"2008-06-25T13:15:44.846Z\", \"UserID\": \"ex sit v\", \"SalesPerson\": \"ea sed Du\", \"ContinueURL\": \"elit do exer\", \"AlternateOrderID\": \"enim ullamco\", \"OrderType\": \"deserunt p\", \"PaymentTokenID\": -7486438, \"BillingFirstName\": \"officia qui\", \"BillingLastName\": \"occaecat ut amet dolore Duis\", \"BillingCompany\": \"sunt\", \"BillingAddress\": \"Ut consectetur\", \"BillingAddress2\": \"nostrud\", \"BillingCity\": \"anim est\", \"BillingState\": \"anim in\", \"BillingZipCode\": \"sed dolor\", \"BillingCountry\": \"consectetur in ullamco conse\", \"BillingPhoneNumber\": \"est\", \"BillingEmail\": \"occaecat pariatur\", \"BillingPaymentMethod\": \"dolor pariatur est fugiat\", \"BillingOnLinePayment\": false, \"BillingPaymentMethodID\": \"magna\", \"ShipmentList\": [], \"OrderItemList\": [], \"PromotionList\": [], \"OrderDiscount\": 4072847.2678701133, \"OrderDiscountCoupon\": -1204504.207070917, \"OrderDiscountPromotion\": 24800753.42261432, \"SalesTax\": -45697427.65446514, \"SalesTax2\": -52287509.961289614, \"SalesTax3\": 17945973.26794225, \"OrderAmount\": 78906000.10147098, \"AffiliateCommission\": -7090869.111720011, \"TransactionList\": [], \"CardType\": \"enim officia\", \"CardNumber\": \"tempor\", \"CardName\": \"nulla nisi\", \"CardExpirationMonth\": \"dolor i\", \"CardExpirationYear\": \"ipsu\", \"CardIssueNumber\": \"proident \", \"CardStartMonth\": \"D\", \"CardStartYear\": \"ipsu\", \"CardAddress\": \"dolor et nisi\", \"CardVerification\": \"incidi\", \"RewardPoints\": \"sint\", \"QuestionList\": [], \"Referer\": \"esse dolore et non\", \"IP\": \"exercit\", \"CustomerComments\": \"enim nostrud ipsum la\", \"InternalComments\": \"dolor\", \"ExternalComments\": \"et id sunt ut Ut\"}", System.Text.Encoding.Default, "application/json"))
{
using (var response = await httpClient.PostAsync("3dCartWebAPI/v1/Orders", content))
{
string responseData = await response.Content.ReadAsStringAsync();
}
}
}
var request = new XMLHttpRequest();
request.open('POST', 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/json');
request.setRequestHeader('SecureURL', '');
request.setRequestHeader('PrivateKey', '');
request.setRequestHeader('Token', '');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
var body = {
'InvoiceNumberPrefix': 'ABC-',
'InvoiceNumber': 123456,
'CustomerID': 1,
'OrderDate': '05/01/2019 09:49',
'OrderStatusID': 4, // Most likely the Shipped status id
'BillingFirstName': 'John',
'BillingLastName': 'Smith',
'BillingCompany': 'ACME, Inc.',
'BillingAddress': '123 Main St.',
'BillingAddress2': 'Suite 100',
'BillingCity': 'Tamarac',
'BillingState': 'FL',
'BillingZipCode': '33321',
'BillingCountry': 'US',
'BillingPhoneNumber': '8008286650',
'BillingEmail': 'john.smith@acme.com',
'BillingPaymentMethod': 'Payment Processor',
'BillingOnLinePayment': false,
'BillingPaymentMethodID': '123',
'ShipmentList': [
{
'ShipmentBoxes': 1,
'ShipmentInternalComment': 'Extra packing material',
'ShipmentOrderStatus': 1, // Most likely the Shipped status id
'ShipmentAddress': '123 Main St.',
'ShipmentAddress2': 'Suite 100',
'ShipmentAlias': 'Alias',
'ShipmentCity': 'Tamarac',
'ShipmentCompany': 'ACME, Inc.',
'ShipmentCost': 10.00,
'ShipmentCountry': 'US',
'ShipmentEmail': 'john.smith@acme.com',
'ShipmentFirstName': 'John',
'ShipmentLastName': 'Smith',
'ShipmentMethodName': 'UPS Ground',
'ShipmentShippedDate': '05/01/2019 09:49',
'ShipmentPhone': '8008286650',
'ShipmentState': 'FL',
'ShipmentZipCode': '33321',
'ShipmentTax': 0.00,
'ShipmentWeight': 1.50,
'ShipmentTrackingCode': 'ABC12345678901234567890',
'ShipmentNumber': 1,
}
],
'OrderItemList': [
{
'CatalogID': 123456,
'ItemID': 'SKU-SAMPLE',
'ItemQuantity': 1,
'ItemUnitPrice': 9.99,
'ItemWeight': 2.5,
'ItemDateAdded': '05/01/2019 09:49',
}
],
'SalesTax': 0.60,
'OrderAmount': 20.59,
};
request.send(JSON.stringify(body));
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
values = '{
"InvoiceNumberPrefix": "ABC-",
"InvoiceNumber": 123456,
"CustomerID": 1,
"OrderDate": "05/01/2019 09:49",
"OrderStatusID": 4, // Most likely the Shipped status id
"BillingFirstName": "John",
"BillingLastName": "Smith",
"BillingCompany": "ACME, Inc.",
"BillingAddress": "123 Main St.",
"BillingAddress2": "Suite 100",
"BillingCity": "Tamarac",
"BillingState": "FL",
"BillingZipCode": "33321",
"BillingCountry": "US",
"BillingPhoneNumber": "8008286650",
"BillingEmail": "john.smith@acme.com",
"BillingPaymentMethod": "Payment Processor",
"BillingOnLinePayment": false,
"BillingPaymentMethodID": "123",
"ShipmentList": [
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "Extra packing material",
"ShipmentOrderStatus": 1, // Most likely the Shipped status id
"ShipmentAddress": "123 Main St.",
"ShipmentAddress2": "Suite 100",
"ShipmentAlias": "Alias",
"ShipmentCity": "Tamarac",
"ShipmentCompany": "ACME, Inc.",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "john.smith@acme.com",
"ShipmentFirstName": "John",
"ShipmentLastName": "Smith",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "8008286650",
"ShipmentState": "FL",
"ShipmentZipCode": "33321",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "ABC12345678901234567890",
"ShipmentNumber": 1,
}
],
"OrderItemList": [
{
"CatalogID": 123456,
"ItemID": "SKU-SAMPLE",
"ItemQuantity": 1,
"ItemUnitPrice": 9.99,
"ItemWeight": 2.5,
"ItemDateAdded": "05/01/2019 09:49",
}
],
"SalesTax": 0.60,
"OrderAmount": 20.59,
}'
headers = {
:content_type => 'application/json',
:accept => 'application/json',
:secureurl => '',
:privatekey => '',
:token => ''
}
response = RestClient.post 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=', values, headers
puts response
from urllib2 import Request, urlopen
values = """
{
"InvoiceNumberPrefix": "ABC-",
"InvoiceNumber": 123456,
"CustomerID": 1,
"OrderDate": "05/01/2019 09:49",
"OrderStatusID": 4, // Most likely the Shipped status id
"BillingFirstName": "John",
"BillingLastName": "Smith",
"BillingCompany": "ACME, Inc.",
"BillingAddress": "123 Main St.",
"BillingAddress2": "Suite 100",
"BillingCity": "Tamarac",
"BillingState": "FL",
"BillingZipCode": "33321",
"BillingCountry": "US",
"BillingPhoneNumber": "8008286650",
"BillingEmail": "john.smith@acme.com",
"BillingPaymentMethod": "Payment Processor",
"BillingOnLinePayment": false,
"BillingPaymentMethodID": "123",
"ShipmentList": [
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "Extra packing material",
"ShipmentOrderStatus": 1, // Most likely the Shipped status id
"ShipmentAddress": "123 Main St.",
"ShipmentAddress2": "Suite 100",
"ShipmentAlias": "Alias",
"ShipmentCity": "Tamarac",
"ShipmentCompany": "ACME, Inc.",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "john.smith@acme.com",
"ShipmentFirstName": "John",
"ShipmentLastName": "Smith",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "8008286650",
"ShipmentState": "FL",
"ShipmentZipCode": "33321",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "ABC12345678901234567890",
"ShipmentNumber": 1,
}
],
"OrderItemList": [
{
"CatalogID": 123456,
"ItemID": "SKU-SAMPLE",
"ItemQuantity": 1,
"ItemUnitPrice": 9.99,
"ItemWeight": 2.5,
"ItemDateAdded": "05/01/2019 09:49",
}
],
"SalesTax": 0.60,
"OrderAmount": 20.59,
}
"""
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'SecureURL': '',
'PrivateKey': '',
'Token': ''
}
request = Request('https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=', data=values, headers=headers)
response_body = urlopen(request).read()
print response_body
Once the prerequisites are taken care of, orders can be imported using the POST method to create an order. In order example 1 to the right, you can see the most basic elements necessary to create a new order. In addition to the CustomerID, BillingPaymentMethodID, and CatalogID mention previously, it contains the invoice number, billing address, shipping address and cost, and the list of items ordered.
Managing shipments
Not every order has one shipment with one item. There are cases where the order will have multiple shipments, each containing multiple items. While we can't cover every scenario, the following is an example of tracking two separate shipments, each with one item.
1. Add the needed number of shipments when creating the order
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, "{
\"InvoiceNumberPrefix\": \"ABC-\",
\"InvoiceNumber\": 123456,
\"CustomerID\": 1,
\"OrderDate\": \"05/01/2019 09:49\",
\"OrderStatusID\": 4, // Most likely the Shipped status id
\"BillingFirstName\": \"John\",
\"BillingLastName\": \"Smith\",
\"BillingCompany\": \"ACME, Inc.\",
\"BillingAddress\": \"123 Main St.\",
\"BillingAddress2\": \"Suite 100\",
\"BillingCity\": \"Tamarac\",
\"BillingState\": \"FL\",
\"BillingZipCode\": \"33321\",
\"BillingCountry\": \"US\",
\"BillingPhoneNumber\": \"8008286650\",
\"BillingEmail\": \"john.smith@acme.com\",
\"BillingPaymentMethod\": \"Payment Processor\",
\"BillingOnLinePayment\": false,
\"BillingPaymentMethodID\": \"123\",
\"ShipmentList\": [
{
\"ShipmentBoxes\": 1,
\"ShipmentInternalComment\": \"Extra packing material\",
\"ShipmentOrderStatus\": 4,
\"ShipmentAddress\": \"123 Main St.\",
\"ShipmentAddress2\": \"Suite 100\",
\"ShipmentAlias\": \"Alias\",
\"ShipmentCity\": \"Tamarac\",
\"ShipmentCompany\": \"ACME, Inc.\",
\"ShipmentCost\": 10.00,
\"ShipmentCountry\": \"US\",
\"ShipmentEmail\": \"john.smith@acme.com\",
\"ShipmentFirstName\": \"John\",
\"ShipmentLastName\": \"Smith\",
\"ShipmentMethodName\": \"UPS Ground\",
\"ShipmentShippedDate\": \"05/01/2019 09:49\",
\"ShipmentPhone\": \"8008286650\",
\"ShipmentState\": \"FL\",
\"ShipmentZipCode\": \"33321\",
\"ShipmentTax\": 0.00,
\"ShipmentWeight\": 1.50,
\"ShipmentTrackingCode\": \"ABC12345678901234567890\",
\"ShipmentNumber\": 1,
},
{
\"ShipmentBoxes\": 1,
\"ShipmentInternalComment\": \"\",
\"ShipmentOrderStatus\": 4,
\"ShipmentAddress\": \"112 1/2 Beacon Street\",
\"ShipmentAddress2\": \"c/o Cheers\",
\"ShipmentCity\": \"Boston\",
\"ShipmentCompany\": \"Cheers\",
\"ShipmentCost\": 10.00,
\"ShipmentCountry\": \"US\",
\"ShipmentEmail\": \"cliff.claven@cheers.com\",
\"ShipmentFirstName\": \"Cliff\",
\"ShipmentLastName\": \"Clavin\",
\"ShipmentMethodName\": \"UPS Ground\",
\"ShipmentShippedDate\": \"05/01/2019 09:49\",
\"ShipmentPhone\": \"6172279605\",
\"ShipmentState\": \"FL\",
\"ShipmentZipCode\": \"02108\",
\"ShipmentTax\": 0.00,
\"ShipmentWeight\": 1.50,
\"ShipmentTrackingCode\": \"XYZ987654321987654321\",
\"ShipmentNumber\": 2,
}
],
\"OrderItemList\": [
{
\"CatalogID\": 123456,
\"ItemID\": \"SKU-SAMPLE\",
\"ItemQuantity\": 1,
\"ItemUnitPrice\": 9.99,
\"ItemWeight\": 2.5,
\"ItemDateAdded\": \"05/01/2019 09:49\",
}
{
\"CatalogID\": 123456,
\"ItemID\": \"SKU-SAMPLE\",
\"ItemQuantity\": 1,
\"ItemUnitPrice\": 9.99,
\"ItemWeight\": 2.5,
\"ItemDateAdded\": \"05/01/2019 09:49\",
}
],
\"SalesTax\": 0.60,
\"OrderAmount\": 31.18,
}");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Accept: application/json",
"SecureURL: ",
"PrivateKey: ",
"Token: "
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;
var baseAddress = new Uri("https://apirest.3dcart.com/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("accept", "application/json");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("secureurl", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("privatekey", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("token", "");
using (var content = new StringContent("{ \"InvoiceNumberPrefix\": \"ut ex\", \"InvoiceNumber\": -76055332, \"OrderID\": 7966749, \"CustomerID\": -42238041, \"OrderDate\": \"1969-08-06T11:55:32.817Z\", \"OrderStatusID\": 25219641, \"LastUpdate\": \"2008-06-25T13:15:44.846Z\", \"UserID\": \"ex sit v\", \"SalesPerson\": \"ea sed Du\", \"ContinueURL\": \"elit do exer\", \"AlternateOrderID\": \"enim ullamco\", \"OrderType\": \"deserunt p\", \"PaymentTokenID\": -7486438, \"BillingFirstName\": \"officia qui\", \"BillingLastName\": \"occaecat ut amet dolore Duis\", \"BillingCompany\": \"sunt\", \"BillingAddress\": \"Ut consectetur\", \"BillingAddress2\": \"nostrud\", \"BillingCity\": \"anim est\", \"BillingState\": \"anim in\", \"BillingZipCode\": \"sed dolor\", \"BillingCountry\": \"consectetur in ullamco conse\", \"BillingPhoneNumber\": \"est\", \"BillingEmail\": \"occaecat pariatur\", \"BillingPaymentMethod\": \"dolor pariatur est fugiat\", \"BillingOnLinePayment\": false, \"BillingPaymentMethodID\": \"magna\", \"ShipmentList\": [], \"OrderItemList\": [], \"PromotionList\": [], \"OrderDiscount\": 4072847.2678701133, \"OrderDiscountCoupon\": -1204504.207070917, \"OrderDiscountPromotion\": 24800753.42261432, \"SalesTax\": -45697427.65446514, \"SalesTax2\": -52287509.961289614, \"SalesTax3\": 17945973.26794225, \"OrderAmount\": 78906000.10147098, \"AffiliateCommission\": -7090869.111720011, \"TransactionList\": [], \"CardType\": \"enim officia\", \"CardNumber\": \"tempor\", \"CardName\": \"nulla nisi\", \"CardExpirationMonth\": \"dolor i\", \"CardExpirationYear\": \"ipsu\", \"CardIssueNumber\": \"proident \", \"CardStartMonth\": \"D\", \"CardStartYear\": \"ipsu\", \"CardAddress\": \"dolor et nisi\", \"CardVerification\": \"incidi\", \"RewardPoints\": \"sint\", \"QuestionList\": [], \"Referer\": \"esse dolore et non\", \"IP\": \"exercit\", \"CustomerComments\": \"enim nostrud ipsum la\", \"InternalComments\": \"dolor\", \"ExternalComments\": \"et id sunt ut Ut\"}", System.Text.Encoding.Default, "application/json"))
{
using (var response = await httpClient.PostAsync("3dCartWebAPI/v1/Orders", content))
{
string responseData = await response.Content.ReadAsStringAsync();
}
}
}
var request = new XMLHttpRequest();
request.open('POST', 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/json');
request.setRequestHeader('SecureURL', '');
request.setRequestHeader('PrivateKey', '');
request.setRequestHeader('Token', '');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
var body = {
'InvoiceNumberPrefix': 'ABC-',
'InvoiceNumber': 123456,
'CustomerID': 1,
'OrderDate': '05/01/2019 09:49',
'OrderStatusID': 4, // Most likely the Shipped status id
'BillingFirstName': 'John',
'BillingLastName': 'Smith',
'BillingCompany': 'ACME, Inc.',
'BillingAddress': '123 Main St.',
'BillingAddress2': 'Suite 100',
'BillingCity': 'Tamarac',
'BillingState': 'FL',
'BillingZipCode': '33321',
'BillingCountry': 'US',
'BillingPhoneNumber': '8008286650',
'BillingEmail': 'john.smith@acme.com',
'BillingPaymentMethod': 'Payment Processor',
'BillingOnLinePayment': false,
'BillingPaymentMethodID': '123',
'ShipmentList': [
{
'ShipmentBoxes': 1,
'ShipmentInternalComment': 'Extra packing material',
'ShipmentOrderStatus': 4,
'ShipmentAddress': '123 Main St.',
'ShipmentAddress2': 'Suite 100',
'ShipmentAlias': 'Alias',
'ShipmentCity': 'Tamarac',
'ShipmentCompany': 'ACME, Inc.',
'ShipmentCost': 10.00,
'ShipmentCountry': 'US',
'ShipmentEmail': 'john.smith@acme.com',
'ShipmentFirstName': 'John',
'ShipmentLastName': 'Smith',
'ShipmentMethodName': 'UPS Ground',
'ShipmentShippedDate': '05/01/2019 09:49',
'ShipmentPhone': '8008286650',
'ShipmentState': 'FL',
'ShipmentZipCode': '33321',
'ShipmentTax': 0.00,
'ShipmentWeight': 1.50,
'ShipmentTrackingCode': 'ABC12345678901234567890',
'ShipmentNumber': 1,
},
{
'ShipmentBoxes': 1,
'ShipmentInternalComment': '',
'ShipmentOrderStatus': 4,
'ShipmentAddress': '112 1/2 Beacon Street',
'ShipmentAddress2': 'c/o Cheers',
'ShipmentCity': 'Boston',
'ShipmentCompany': 'Cheers',
'ShipmentCost': 10.00,
'ShipmentCountry': 'US',
'ShipmentEmail': 'cliff.claven@cheers.com',
'ShipmentFirstName': 'Cliff',
'ShipmentLastName': 'Clavin',
'ShipmentMethodName': 'UPS Ground',
'ShipmentShippedDate': '05/01/2019 09:49',
'ShipmentPhone': '6172279605',
'ShipmentState': 'FL',
'ShipmentZipCode': '02108',
'ShipmentTax': 0.00,
'ShipmentWeight': 1.50,
'ShipmentTrackingCode': 'XYZ987654321987654321',
'ShipmentNumber': 2,
}
],
'OrderItemList': [
{
'CatalogID': 123456,
'ItemID': 'SKU-SAMPLE',
'ItemQuantity': 1,
'ItemUnitPrice': 9.99,
'ItemWeight': 2.5,
'ItemDateAdded': '05/01/2019 09:49',
}
{
'CatalogID': 123456,
'ItemID': 'SKU-SAMPLE',
'ItemQuantity': 1,
'ItemUnitPrice': 9.99,
'ItemWeight': 2.5,
'ItemDateAdded': '05/01/2019 09:49',
}
],
'SalesTax': 0.60,
'OrderAmount': 31.18,
};
request.send(JSON.stringify(body));
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
values = '{
"InvoiceNumberPrefix": "ABC-",
"InvoiceNumber": 123456,
"CustomerID": 1,
"OrderDate": "05/01/2019 09:49",
"OrderStatusID": 4, // Most likely the Shipped status id
"BillingFirstName": "John",
"BillingLastName": "Smith",
"BillingCompany": "ACME, Inc.",
"BillingAddress": "123 Main St.",
"BillingAddress2": "Suite 100",
"BillingCity": "Tamarac",
"BillingState": "FL",
"BillingZipCode": "33321",
"BillingCountry": "US",
"BillingPhoneNumber": "8008286650",
"BillingEmail": "john.smith@acme.com",
"BillingPaymentMethod": "Payment Processor",
"BillingOnLinePayment": false,
"BillingPaymentMethodID": "123",
"ShipmentList": [
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "Extra packing material",
"ShipmentOrderStatus": 4,
"ShipmentAddress": "123 Main St.",
"ShipmentAddress2": "Suite 100",
"ShipmentAlias": "Alias",
"ShipmentCity": "Tamarac",
"ShipmentCompany": "ACME, Inc.",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "john.smith@acme.com",
"ShipmentFirstName": "John",
"ShipmentLastName": "Smith",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "8008286650",
"ShipmentState": "FL",
"ShipmentZipCode": "33321",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "ABC12345678901234567890",
"ShipmentNumber": 1,
},
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "",
"ShipmentOrderStatus": 4,
"ShipmentAddress": "112 1/2 Beacon Street",
"ShipmentAddress2": "c/o Cheers",
"ShipmentCity": "Boston",
"ShipmentCompany": "Cheers",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "cliff.claven@cheers.com",
"ShipmentFirstName": "Cliff",
"ShipmentLastName": "Clavin",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "6172279605",
"ShipmentState": "FL",
"ShipmentZipCode": "02108",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "XYZ987654321987654321",
"ShipmentNumber": 2,
}
],
"OrderItemList": [
{
"CatalogID": 123456,
"ItemID": "SKU-SAMPLE",
"ItemQuantity": 1,
"ItemUnitPrice": 9.99,
"ItemWeight": 2.5,
"ItemDateAdded": "05/01/2019 09:49",
}
{
"CatalogID": 123456,
"ItemID": "SKU-SAMPLE",
"ItemQuantity": 1,
"ItemUnitPrice": 9.99,
"ItemWeight": 2.5,
"ItemDateAdded": "05/01/2019 09:49",
}
],
"SalesTax": 0.60,
"OrderAmount": 31.18,
}'
headers = {
:content_type => 'application/json',
:accept => 'application/json',
:secureurl => '',
:privatekey => '',
:token => ''
}
response = RestClient.post 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=', values, headers
puts response
from urllib2 import Request, urlopen
values = """
{
"InvoiceNumberPrefix": "ABC-",
"InvoiceNumber": 123456,
"CustomerID": 1,
"OrderDate": "05/01/2019 09:49",
"OrderStatusID": 4, // Most likely the Shipped status id
"BillingFirstName": "John",
"BillingLastName": "Smith",
"BillingCompany": "ACME, Inc.",
"BillingAddress": "123 Main St.",
"BillingAddress2": "Suite 100",
"BillingCity": "Tamarac",
"BillingState": "FL",
"BillingZipCode": "33321",
"BillingCountry": "US",
"BillingPhoneNumber": "8008286650",
"BillingEmail": "john.smith@acme.com",
"BillingPaymentMethod": "Payment Processor",
"BillingOnLinePayment": false,
"BillingPaymentMethodID": "123",
"ShipmentList": [
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "Extra packing material",
"ShipmentOrderStatus": 4,
"ShipmentAddress": "123 Main St.",
"ShipmentAddress2": "Suite 100",
"ShipmentAlias": "Alias",
"ShipmentCity": "Tamarac",
"ShipmentCompany": "ACME, Inc.",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "john.smith@acme.com",
"ShipmentFirstName": "John",
"ShipmentLastName": "Smith",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "8008286650",
"ShipmentState": "FL",
"ShipmentZipCode": "33321",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "ABC12345678901234567890",
"ShipmentNumber": 1,
},
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "",
"ShipmentOrderStatus": 4,
"ShipmentAddress": "112 1/2 Beacon Street",
"ShipmentAddress2": "c/o Cheers",
"ShipmentCity": "Boston",
"ShipmentCompany": "Cheers",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "cliff.claven@cheers.com",
"ShipmentFirstName": "Cliff",
"ShipmentLastName": "Clavin",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "6172279605",
"ShipmentState": "FL",
"ShipmentZipCode": "02108",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "XYZ987654321987654321",
"ShipmentNumber": 2,
}
],
"OrderItemList": [
{
"CatalogID": 123456,
"ItemID": "SKU-SAMPLE",
"ItemQuantity": 1,
"ItemUnitPrice": 9.99,
"ItemWeight": 2.5,
"ItemDateAdded": "05/01/2019 09:49",
}
{
"CatalogID": 123456,
"ItemID": "SKU-SAMPLE",
"ItemQuantity": 1,
"ItemUnitPrice": 9.99,
"ItemWeight": 2.5,
"ItemDateAdded": "05/01/2019 09:49",
}
],
"SalesTax": 0.60,
"OrderAmount": 31.18,
}
"""
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'SecureURL': '',
'PrivateKey': '',
'Token': ''
}
request = Request('https://apirest.3dcart.com/3dCartWebAPI/v1/Orders?bypassorderprocessing=&bypassorderemail=', data=values, headers=headers)
response_body = urlopen(request).read()
print response_body
"ShipmentList": [
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "Extra packing material",
"ShipmentOrderStatus": 4,
"ShipmentAddress": "123 Main St.",
"ShipmentAddress2": "Suite 100",
"ShipmentAlias": "Alias",
"ShipmentCity": "Tamarac",
"ShipmentCompany": "ACME, Inc.",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "john.smith@acme.com",
"ShipmentFirstName": "John",
"ShipmentLastName": "Smith",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "8008286650",
"ShipmentState": "FL",
"ShipmentZipCode": "33321",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "ABC12345678901234567890",
"ShipmentNumber": 1,
},
{
"ShipmentBoxes": 1,
"ShipmentInternalComment": "",
"ShipmentOrderStatus": 4,
"ShipmentAddress": "112 1/2 Beacon Street",
"ShipmentAddress2": "c/o Cheers",
"ShipmentCity": "Boston",
"ShipmentCompany": "Cheers",
"ShipmentCost": 10.00,
"ShipmentCountry": "US",
"ShipmentEmail": "cliff.claven@cheers.com",
"ShipmentFirstName": "Cliff",
"ShipmentLastName": "Clavin",
"ShipmentMethodName": "UPS Ground",
"ShipmentShippedDate": "05/01/2019 09:49",
"ShipmentPhone": "6172279605",
"ShipmentState": "FL",
"ShipmentZipCode": "02108",
"ShipmentTax": 0.00,
"ShipmentWeight": 1.50,
"ShipmentTrackingCode": "XYZ987654321987654321",
"ShipmentNumber": 2,
}
],
The shipment example 1 to the right shows a "ShipmentList" collection with 2 shipments having separate addresses and tracking information. The ShipmentID field is not included, since we're creating a new order and the ShipmentID's will be automatically generated by the 3dcart software. When the order is created, the response will contain the OrderID value (see Create an order for more information). This will be needed for the next step. Next
2. Retrieve the order
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Accept: application/json",
"SecureURL: ",
"PrivateKey: ",
"Token: "
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;
var baseAddress = new Uri("https://apirest.3dcart.com/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("accept", "application/json");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("secureurl", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("privatekey", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("token", "");
using(var response = await httpClient.GetAsync("3dCartWebAPI/v1/Orders/{orderid}"))
{
string responseData = await response.Content.ReadAsStringAsync();
}
}
var request = new XMLHttpRequest();
request.open('GET', 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/json');
request.setRequestHeader('SecureURL', '');
request.setRequestHeader('PrivateKey', '');
request.setRequestHeader('Token', '');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
request.send();
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
headers = {
:content_type => 'application/json',
:accept => 'application/json',
:secureurl => '',
:privatekey => '',
:token => ''
}
response = RestClient.get 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}', headers
puts response
from urllib2 import Request, urlopen
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'SecureURL': '',
'PrivateKey': '',
'Token': ''
}
request = Request('https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}', headers=headers)
response_body = urlopen(request).read()
print response_body
Using the OrderId from the previous step, use the Orders method to retrieve an order by id, or the Order Shipments method to retrieve the list of shipments. This will contain the ShipmentID you will need in order to assign the items within the order to the individual shipments.
In most scenarios, using the Order Shipments method is the easiest method, however, if two of the same item is purchased with 1 in each shipment, you will need to use the Orders method. The orders method will contain the full OrderItemList. The OrderItemList will contain the ItemIndexID for each item (See the OrderItem object for more information on the OrderItem object). This is the unique ID value each item has in the cart. You will need the ItemIndexID value to update the items in the next step. Prev Next
3. Update the items
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}/Items");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, "[
{
\"CatalogID\": -51009885,
\"ItemIndexID\": -38091580,
\"ItemID\": \"adipisicing do ut officia in\",
\"ItemShipmentID\": 11031062,
\"ItemQuantity\": 59015700.77777743,
\"ItemWarehouseID\": 69759704,
\"ItemDescription\": \"irure nisi proident est\",
\"ItemUnitPrice\": -30084251.563731313,
\"ItemWeight\": 12090001.066257238,
\"ItemOptionPrice\": -68498097.38445307,
\"ItemAdditionalField1\": \"est mollit aute\",
\"ItemAdditionalField2\": \"aute exercitation ex\",
\"ItemAdditionalField3\": \"ad minim ea incididunt\",
\"ItemPageAdded\": \"sunt nisi adipisicing do Duis\",
\"ItemAvailability\": \"dolore\",
\"ItemDateAdded\": \"2003-04-05T08:48:08.259Z\",
\"ItemUnitCost\": -23455627.019790664,
\"ItemUnitStock\": -7821036.362208262,
\"ItemOptions\": \"aute\",
\"ItemCatalogIDOptions\": \"ipsum esse cillum\",
\"ItemSerial\": \"labore\",
\"ItemImage1\": \"laboris elit in amet\",
\"ItemImage2\": \"cillum\",
\"ItemImage3\": \"aliquip\",
\"ItemImage4\": \"adipisicing ipsum\",
\"ItemWarehouseLocation\": \"occaecat ullamco\",
\"ItemWarehouseBin\": \"dolore proident eu occaecat\",
\"ItemWarehouseAisle\": \"nulla ut velit\",
\"ItemWarehouseCustom\": \"sit Lorem\",
\"RecurringOrderFrequency\": 73743421
}
]");
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
"Content-Type: application/json",
"Accept: application/json",
"SecureURL: ",
"PrivateKey: ",
"Token: "
));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
//Common testing requirement. If you are consuming an API in a sandbox/test region, uncomment this line of code ONLY for non production uses.
//System.Net.ServicePointManager.ServerCertificateValidationCallback = delegate { return true; };
//Be sure to run "Install-Package Microsoft.Net.Http" from your nuget command line.
using System;
using System.Net.Http;
var baseAddress = new Uri("https://apirest.3dcart.com/");
using (var httpClient = new HttpClient{ BaseAddress = baseAddress })
{
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("accept", "application/json");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("secureurl", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("privatekey", "");
httpClient.DefaultRequestHeaders.TryAddWithoutValidation("token", "");
using (var content = new StringContent("[ { \"CatalogID\": -51009885, \"ItemIndexID\": -38091580, \"ItemID\": \"adipisicing do ut officia in\", \"ItemShipmentID\": 11031062, \"ItemQuantity\": 59015700.77777743, \"ItemWarehouseID\": 69759704, \"ItemDescription\": \"irure nisi proident est\", \"ItemUnitPrice\": -30084251.563731313, \"ItemWeight\": 12090001.066257238, \"ItemOptionPrice\": -68498097.38445307, \"ItemAdditionalField1\": \"est mollit aute\", \"ItemAdditionalField2\": \"aute exercitation ex\", \"ItemAdditionalField3\": \"ad minim ea incididunt\", \"ItemPageAdded\": \"sunt nisi adipisicing do Duis\", \"ItemAvailability\": \"dolore\", \"ItemDateAdded\": \"2003-04-05T08:48:08.259Z\", \"ItemUnitCost\": -23455627.019790664, \"ItemUnitStock\": -7821036.362208262, \"ItemOptions\": \"aute\", \"ItemCatalogIDOptions\": \"ipsum esse cillum\", \"ItemSerial\": \"labore\", \"ItemImage1\": \"laboris elit in amet\", \"ItemImage2\": \"cillum\", \"ItemImage3\": \"aliquip\", \"ItemImage4\": \"adipisicing ipsum\", \"ItemWarehouseLocation\": \"occaecat ullamco\", \"ItemWarehouseBin\": \"dolore proident eu occaecat\", \"ItemWarehouseAisle\": \"nulla ut velit\", \"ItemWarehouseCustom\": \"sit Lorem\", \"RecurringOrderFrequency\": 73743421 }]", System.Text.Encoding.Default, "application/json"))
{
using (var response = await httpClient.PutAsync("3dCartWebAPI/v1/Orders/{orderid}/Items", content))
{
string responseData = await response.Content.ReadAsStringAsync();
}
}
}
var request = new XMLHttpRequest();
request.open('PUT', 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}/Items');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/json');
request.setRequestHeader('SecureURL', '');
request.setRequestHeader('PrivateKey', '');
request.setRequestHeader('Token', '');
request.onreadystatechange = function () {
if (this.readyState === 4) {
console.log('Status:', this.status);
console.log('Headers:', this.getAllResponseHeaders());
console.log('Body:', this.responseText);
}
};
var body = [
{
'CatalogID': -51009885,
'ItemIndexID': -38091580,
'ItemID': 'adipisicing do ut officia in',
'ItemShipmentID': 11031062,
'ItemQuantity': 59015700.77777743,
'ItemWarehouseID': 69759704,
'ItemDescription': 'irure nisi proident est',
'ItemUnitPrice': -30084251.563731313,
'ItemWeight': 12090001.066257238,
'ItemOptionPrice': -68498097.38445307,
'ItemAdditionalField1': 'est mollit aute',
'ItemAdditionalField2': 'aute exercitation ex',
'ItemAdditionalField3': 'ad minim ea incididunt',
'ItemPageAdded': 'sunt nisi adipisicing do Duis',
'ItemAvailability': 'dolore',
'ItemDateAdded': '2003-04-05T08:48:08.259Z',
'ItemUnitCost': -23455627.019790664,
'ItemUnitStock': -7821036.362208262,
'ItemOptions': 'aute',
'ItemCatalogIDOptions': 'ipsum esse cillum',
'ItemSerial': 'labore',
'ItemImage1': 'laboris elit in amet',
'ItemImage2': 'cillum',
'ItemImage3': 'aliquip',
'ItemImage4': 'adipisicing ipsum',
'ItemWarehouseLocation': 'occaecat ullamco',
'ItemWarehouseBin': 'dolore proident eu occaecat',
'ItemWarehouseAisle': 'nulla ut velit',
'ItemWarehouseCustom': 'sit Lorem',
'RecurringOrderFrequency': 73743421
}
];
request.send(JSON.stringify(body));
require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest_client'
values = '[
{
"CatalogID": -51009885,
"ItemIndexID": -38091580,
"ItemID": "adipisicing do ut officia in",
"ItemShipmentID": 11031062,
"ItemQuantity": 59015700.77777743,
"ItemWarehouseID": 69759704,
"ItemDescription": "irure nisi proident est",
"ItemUnitPrice": -30084251.563731313,
"ItemWeight": 12090001.066257238,
"ItemOptionPrice": -68498097.38445307,
"ItemAdditionalField1": "est mollit aute",
"ItemAdditionalField2": "aute exercitation ex",
"ItemAdditionalField3": "ad minim ea incididunt",
"ItemPageAdded": "sunt nisi adipisicing do Duis",
"ItemAvailability": "dolore",
"ItemDateAdded": "2003-04-05T08:48:08.259Z",
"ItemUnitCost": -23455627.019790664,
"ItemUnitStock": -7821036.362208262,
"ItemOptions": "aute",
"ItemCatalogIDOptions": "ipsum esse cillum",
"ItemSerial": "labore",
"ItemImage1": "laboris elit in amet",
"ItemImage2": "cillum",
"ItemImage3": "aliquip",
"ItemImage4": "adipisicing ipsum",
"ItemWarehouseLocation": "occaecat ullamco",
"ItemWarehouseBin": "dolore proident eu occaecat",
"ItemWarehouseAisle": "nulla ut velit",
"ItemWarehouseCustom": "sit Lorem",
"RecurringOrderFrequency": 73743421
}
]'
headers = {
:content_type => 'application/json',
:accept => 'application/json',
:secureurl => '',
:privatekey => '',
:token => ''
}
response = RestClient.put 'https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}/Items', values, headers
puts response
from urllib2 import Request, urlopen
values = """
[
{
"CatalogID": -51009885,
"ItemIndexID": -38091580,
"ItemID": "adipisicing do ut officia in",
"ItemShipmentID": 11031062,
"ItemQuantity": 59015700.77777743,
"ItemWarehouseID": 69759704,
"ItemDescription": "irure nisi proident est",
"ItemUnitPrice": -30084251.563731313,
"ItemWeight": 12090001.066257238,
"ItemOptionPrice": -68498097.38445307,
"ItemAdditionalField1": "est mollit aute",
"ItemAdditionalField2": "aute exercitation ex",
"ItemAdditionalField3": "ad minim ea incididunt",
"ItemPageAdded": "sunt nisi adipisicing do Duis",
"ItemAvailability": "dolore",
"ItemDateAdded": "2003-04-05T08:48:08.259Z",
"ItemUnitCost": -23455627.019790664,
"ItemUnitStock": -7821036.362208262,
"ItemOptions": "aute",
"ItemCatalogIDOptions": "ipsum esse cillum",
"ItemSerial": "labore",
"ItemImage1": "laboris elit in amet",
"ItemImage2": "cillum",
"ItemImage3": "aliquip",
"ItemImage4": "adipisicing ipsum",
"ItemWarehouseLocation": "occaecat ullamco",
"ItemWarehouseBin": "dolore proident eu occaecat",
"ItemWarehouseAisle": "nulla ut velit",
"ItemWarehouseCustom": "sit Lorem",
"RecurringOrderFrequency": 73743421
}
]
"""
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'SecureURL': '',
'PrivateKey': '',
'Token': ''
}
request = Request('https://apirest.3dcart.com/3dCartWebAPI/v1/Orders/{orderid}/Items', data=values, headers=headers)
request.get_method = lambda: 'PUT'
response_body = urlopen(request).read()
print response_body
Using the Order Items method to update a list of items, match the item CatalogID or ItemIndexID with its' corresponding ItemShipmentID in order to assign the items to a specific shipment. This will allow the order to be split into multiple shipments with their own tracking information. Prev
Update tracking for shipped orders
Update shipment tracking
[
{
"ShipmentID": 1,
"ShipmentTrackingCode": "abc1234567890"
},
{
"ShipmentID": 2,
"ShipmentTrackingCode": "zyx0987654321"
}
]
Updating shipment tracking information can be done using one of the PUT methods to update order shipments: Update a list of shipments or by specific shipment id. Since you're only updating the tracking information, only the ShipmentID and ShipmentTrackingCode values need to be included in the request, as seen in the example on the right.
Creating new carts from a 3rd party system
The Carts methods allow you to create carts (orders) from external systems (e.g. an external website or blog), that can then allow the external user to be redirected into the store's secure checkout page.
Creating a cart
{
"BillingFirstName": "",
"BillingLastName": "",
"BillingCompany": "",
"BillingAddress": "",
"BillingAddress2": "",
"BillingCity": "",
"BillingState": "",
"BillingZipCode": "",
"BillingCountry": "",
"BillingPhoneNumber": "",
"BillingEmail": "",
"ShipmentAddress": "",
"ShipmentAddress2": "",
"ShipmentCity": "",
"ShipmentCompany": "",
"ShipmentCountry": "",
"ShipmentEmail": "",
"ShipmentFirstName": "",
"ShipmentLastName": "",
"ShipmentPhone": "",
"ShipmentState": "",
"ShipmentZipCode": ""
}
When creating the initial cart from an external system, you usually would not have any of the user's personal billing or shipping information at this point (if you do, great! You can add it in this step.). Normally, the user would have only have clicked an "Add to cart" button, for example, so you would create a new order with an empty POST request. The response will contain an OrderKey value. This is needed in subsequent steps, so hold onto it.
Adding items to the order
{
"CatalogID": 3828,
"ItemQuantity": 1.1,
"ItemOptions": [
{
"OptionSetID": 1882,
"OptionID": 12396,
"OptionValue": "Small"
}
]
}
Now that you've created the new cart and have the new OrderKey value, using the method to create a cart item can be done as shown with the example on the right. After the item has been added, a GET request to retrieve
Updating item quantity
{
"ItemQuantity": 2
}
Updating the item quantity is easy, as well. Using the method to update a cart item, only the new adjusted item quantity needs to be sent.
Deleting items and/or orders
Items or orders can be deleted using their respective delete methods.
Adding a Frontend Script
The FrontendScripts methods can be used to inject a script into a store's web page. This can be used to supplement the functionality a 3rd party application, such as a chat/service desk or CRM ticketing application.
Inserting the Frontend Script
{
"Placement": "HEAD",
"Code": "<script type=\"text/javascript\" src=\"https://www.example.com/path/to/script.js\"><\/script>",
"DateCreated": "05/02/2019 13:23",
"LastUpdate": "05/02/2019 13:23"
}
When inserting the script, the Placement value will determine where the script is placed. The two options are HEAD and BODY. This will inject the script just before the closing HTML head or body tag (e.g. </head> or </body>).
Importing products
Prerequisites
Importing products uses the Products POST web service (see Create a product for more information)
Creating products with advanced options
Creating a product with advanced options is a multi-step process that can be done following these steps:
Create a product with options
POST https://apirest.3dcart.com/3dCartWebAPI/v1/Products
{
"SKUInfo":{
"SKU":"APITEST01",
"Name":"Testing the API",
"Cost":1.0,
"Price":2.0,
"Currency":"",
"RetailPrice":2.5,
"SalePrice":0.0,
"OnSale":false,
"Stock":100.0
},
"OptionSetList":[
{
"OptionSetName":"Color",
"OptionSorting":1.0,
"OptionRequired":false,
"OptionType":"Dropdown",
"OptionURL":"",
"OptionAdditionalInformation":"",
"OptionSizeLimit":0,
"OptionList":[
{
"OptionName":"Red",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":1.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
},
{
"OptionName":"Black",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":2.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
}
]
},
{
"OptionSetName":"Size",
"OptionSorting":2.0,
"OptionRequired":false,
"OptionType":"Dropdown",
"OptionURL":"",
"OptionAdditionalInformation":"",
"OptionSizeLimit":0,
"OptionList":[
{
"OptionName":"Small",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":1.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
},
{
"OptionName":"Medium",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":2.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
}
]
}
]
}
Response:
[
{
"Key":"CatalogID",
"Value":"61850",
"Status":"201",
"Message":"Created successfully",
}
]
Create a new product with options defined using the Products POST web service - Create a product - and retain the Catalog ID returned in the response.
Retrieve the new product
Response
[
{
"SKUInfo":{
"CatalogID":61850,
"SKU":"APITEST01",
"Name":"Testing the API",
"Cost":1.0,
"Price":2.0,
"Currency":"",
"RetailPrice":2.5,
"SalePrice":0.0,
"OnSale":false,
"Stock":100.0
},
"OptionSetList":[
{
"OptionSetID":21,
"OptionSetName":"Color",
"OptionSorting":1.0,
"OptionRequired":false,
"OptionType":"Dropdown",
"OptionURL":"",
"OptionAdditionalInformation":"",
"OptionSizeLimit":0,
"OptionList":[
{
"OptionID":67,
"OptionName":"Red",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":1.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
},
{
"OptionID":68,
"OptionName":"Black",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":2.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
}
]
},
{
"OptionSetID":22,
"OptionSetName":"Size",
"OptionSorting":2.0,
"OptionRequired":false,
"OptionType":"Dropdown",
"OptionURL":"",
"OptionAdditionalInformation":"",
"OptionSizeLimit":0,
"OptionList":[
{
"OptionID":69,
"OptionName":"Small",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":1.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
},
{
"OptionID":70,
"OptionName":"Medium",
"OptionSelected":false,
"OptionHide":false,
"OptionValue":0.0,
"OptionPartNumber":"",
"OptionSorting":2.0,
"OptionImagePath":"",
"OptionBundleCatalogId":0,
"OptionBundleQuantity":0
}
]
}
]
}
]
Using the Catalog ID returned in the response, retrieve the newly created product using the Products GET web service - Retrieve a specific product by id
GET https://apirest.3dcart.com/3dCartWebAPI/v1/Products/61850
Creating advanced option combinations
{
"SKUInfo":{
"CatalogID":61850
},
"AdvancedOptionList":[
{
"AdvancedOptionCode":"67-69",
"AdvancedOptionSufix":"SKU01",
"AdvancedOptionName":"Red Small",
"AdvancedOptionCost":0,
"AdvancedOptionStock":5,
"AdvancedOptionWeight":1,
"AdvancedOptionGTIN":"123456789"
},
{
"AdvancedOptionCode":"67-70",
"AdvancedOptionSufix":"SKU02",
"AdvancedOptionName":"Red Medium",
"AdvancedOptionCost":0,
"AdvancedOptionStock":5,
"AdvancedOptionWeight":1,
"AdvancedOptionGTIN":"23456789"
},
{
"AdvancedOptionCode":"68-69",
"AdvancedOptionSufix":"SKU03",
"AdvancedOptionName":"Black Small",
"AdvancedOptionCost":0,
"AdvancedOptionStock":5,
"AdvancedOptionWeight":1,
"AdvancedOptionGTIN":"3456789"
},
{
"AdvancedOptionCode":"68-70",
"AdvancedOptionSufix":"SKU04",
"AdvancedOptionName":"Black Medium",
"AdvancedOptionCost":0,
"AdvancedOptionStock":5,
"AdvancedOptionWeight":1,
"AdvancedOptionGTIN":"456789"
}
]
}
Maintaining the same order the option sets were created in and using the Products PUT web service - Update a specific product by id - update the AdvancedOptionList collection of product created in the first step.
PUT https://apirest.3dcart.com/3dCartWebAPI/v1/Products/61850
Webhooks
Admin Login Tokens - SSO
Creating a Single Sign On (SSO) app
Using the Admin Users' Login Token method, it's possible to create a Single Sign On (SSO) application.
For example, using the Login Token method, a request to this URL - http://apirest.3dcart.com/3dCartWebAPI/v1/Admins/57/LoginToken?targetpage=store_modules.asp - would be requesting a Login Token for the Admin User with an id of 57 (you must specify the id of the Admin User and the targetpage) with a redirect to https://secure-url.com/admin/store_modules.asp
The response back from the API will contain a "loginurl" parameter. This parameter will have a value similar to this:
https://secure-url.com/admin/login.asp?action=processtoken&apitoken=dqm13jwpYJD8qJ%2FY0dIgBaUd9Bi5h5LWYAJRecL%2BrEiv4bEwulJO95Pw3nyeOQPyEWdBj1bhzQ%2FP%0D%0AIaRXLmrcnlAWylRfAONvUTKioVNp9jw%3D&targetpage=store_modules.asp
You can then redirect the user to this URL and the login will happen automatically and the user will be redirected to https://secure-url.com/admin/store_modules.asp once completed.