API INTEGRATION
EXAMPLES
The following examples demonstrate request/response for seven common scenarios. They are provided to give you a jump on using the API. The actual content will vary based on the client.
Scenario 1: orderedBy same as shipTo, pre-paid, with no credit card information included
A person orders a product and pays for it at the time the order is placed. The person ordering is the same person who will be getting the product. ShipRight is not processing any payments for this company, so the order is sent as an invoiced order.
{
"lineItems": [
{
"unitPrice": 1.01,
"itemCode": "COMP CHOCOLATES 1LB",
"quantity": 5
}
],
"alternateOrderNumber": "scenario_1",
"ownerCode": "SR",
"orderClass": "DEFAULT",
"campaignCode": "DEF",
"orderTotal": 6.3,
"tax": 0,
"shippingAmount": 1.25,
"shipVia": "RG1",
"orderDate": "2014-05-29T16:00:00Z",
"orderSourceId": "5",
"shipToSameAsBillTo": true,
"orderedBy": {
"address": {
"email": "bilbo@bagend.com",
"address1": "Bag End",
"address2": "165 Pleasant Avenue",
"city": "South Portland",
"region": "Me",
"country": "USA",
"postalCode": "04106"
},
"phones": [
{
"phoneType": "Mobile",
"countryCode": "123",
"areaCode": "987",
"phoneNumber": "1234567"
}
],
"alternateCustomerNumber": "bilbo_1",
"title": "Mr",
"first": "Bilbo",
"middle": "",
"last": "Baggins"
},
"payment": {
"paymentMethodCode": "I",
"prePaid": true,
"paymentInstrumentType": "INVOICE",
"invoice": {
"reference": "scenario_1"
}
}
}
Scenario 2: orderedBy same as shipTo, discounted and pre-paid, with no credit card information included
A person orders a product and pays for it at the time the order is placed. Additionally, the order is discounted by $2. The person ordering is the same person who will be getting the product.
{
"lineItems": [
{
"unitPrice": 1.01,
"itemCode": "COMP CHOCOLATES 1LB",
"quantity": 5
}
],
"alternateOrderNumber": "scenario_2",
"ownerCode": "SR",
"orderClass": "DEFAULT",
"campaignCode": "DEF",
"orderTotal": 4.30,
"tax": 0,
"shippingAmount": 1.25,
"discountApplied": 2.00,
"shipVia": "RG1",
"orderDate": "2014-05-29T16:00:00Z",
"orderSourceId": "5",
"shipToSameAsBillTo": true,
"orderedBy": {
"address": {
"email": "bilbo@bagend.com",
"address1": "Bag End",
"address2": "165 Pleasant Avenue",
"city": "South Portland",
"region": "Me",
"country": "USA",
"postalCode": "04106"
},
"phones": [
{
"phoneType": "Mobile",
"countryCode": "1",
"areaCode": "987",
"phoneNumber": "1234567"
}
],
"alternateCustomerNumber": "bilbo_1",
"title": "Mr",
"first": "Bilbo",
"middle": "",
"last": "Baggins"
},
"payment": {
"paymentMethodCode": "I",
"prePaid": true,
"paymentInstrumentType": "INVOICE",
"invoice": {
"reference": "scenario_2"
}
}
}
Scenario 3: orderedBy same as shipTo, ShipRight to authorize and capture credit card payment A person orders a product and chooses to pay by credit card. However, the card is charged by ShipRight immediately before the order is processed for shipping. The person ordering is the same person who will be getting the product.
{
"lineItems": [
{
"unitPrice": 1.01,
"itemCode": "COMP CHOCOLATES 1LB",
"quantity": 1
}
],
"alternateOrderNumber": "scenario_3",
"ownerCode": "SR",
"orderClass": "DEFAULT",
"campaignCode": "DEF",
"orderTotal": 1.01,
"tax": 0,
"shippingAmount": 0,
"shipVia": "RG1",
"orderDate": "2014-05-29T16:00:00Z",
"orderSourceId": "5",
"shipToSameAsBillTo": true,
"orderedBy": {
"address": {
"email": "smeagol@gladdenfields.com",
"address1": "Stoor",
"address2": "165 Pleasant Avenue",
"city": "South Portland",
"region": "Me",
"country": "USA",
"postalCode": "02110"
},
"phones": [
{
"phoneType": "Mobile",
"countryCode": "123",
"areaCode": "987",
"phoneNumber": "1234567"
}
],
"alternateCustomerNumber": "golum_2",
"title": "Mt",
"first": "smeagol",
"middle": "",
"last": "Golum",
"fullName": ""
},
"payment": {
"paymentMethodCode": "V",
"prePaid": false,
"paymentInstrumentType": "CREDITCARD",
"creditcard": {
"creditCardNumber": "4530910000012345",
"cvnResultCode": "P",
"expiration": "2015-01-01T00:00:00Z"
}
}
}
Scenario 4: Existing customer, standardized orderedBy with different shipTo, pre-paid by cash A person orders a product and pays for it with cash at the time the order is placed. The order is going to be sent to another person at a different address. The order is sent to ShipRight via the API for shipping. customerId is included in the request, as well as the standardized address, with standardized = true.
{
"lineItems": [
{
"unitPrice": 1.01,
"itemCode": "COMP CHOCOLATES 1LB",
"quantity": 1
}
],
"alternateOrderNumber": "scenario_4",
"ownerCode": "SR",
"orderClass": "DEFAULT",
"campaignCode": "DEF",
"orderTotal": 1.01,
"tax": 0,
"shippingAmount": 0,
"shipVia": "RG1",
"orderDate": "2014-05-29T16:00:00Z",
"orderSourceId": "5",
"shipToSameAsBillTo": false,
"orderedBy": {
"address": {
"standardized": true,
"email": "bilbo@bagend.com",
"address1": "BAG END",
"address2": "165 PLEASANT AVE",
"city": "S PORTLAND",
"region": "ME",
"country": "USA",
"postalCode": "04106-6226"
},
"phones": [
{
"phoneType": "Mobile",
"countryCode": "123",
"areaCode": "987",
"phoneNumber": "1234567"
}
],
"customerId": 3309843,
"alternateCustomerNumber": "bilbo_1",
"title": "Mr",
"first": "Bilbo",
"middle": "",
"last": "Baggins"
},
"shipTo": {
"address": {
"email": "sauron@dolGuldur.com",
"address1": "Dol Guldur",
"address2": "165 Pleasant Avenue",
"city": "South Portland",
"region": "Me",
"country": "USA",
"postalCode": "04106"
},
"alternateCustomerNumber": "Aulendil_3",
"title": "",
"first": "Sauron",
"middle": null,
"last": "Aulendil"
},
"payment": {
"paymentMethodCode": "I",
"prePaid": true,
"paymentInstrumentType": "CASH",
"invoice": {
"reference": "scenario_4"
}
}
}
Scenario 5: Existing customer, standardized orderedBy same as shipTo, ShipRight to authorize and capture the credit card payment
An existing customer (someone who has previously placed an order with the same company) orders a product and chooses to pay by credit card. The card is charged by ShipRight immediately before the order is processed for shipping. The person ordering is the same person who will be getting the product. customerId is included in the request, as well as the standardized address, with standardized = true.
{
"lineItems": [
{
"unitPrice": 1.01,
"itemCode": "COMP CHOCOLATES 1LB",
"quantity": 3
}
],
"alternateOrderNumber": "scenario_5",
"ownerCode": "SR",
"orderClass": "DEFAULT",
"campaignCode": "DEF",
"orderTotal": 3.03,
"tax": 0,
"shippingAmount": 0,
"shipVia": "RG1",
"orderDate": "2014-05-29T16:00:00Z",
"orderSourceId": "5",
"shipToSameAsBillTo": true,
"orderedBy": {
"address": {
"standardized": true,
"email": "bilbo@bagend.com",
"address1": "BAG END",
"address2": "165 PLEASANT AVE",
"city": "S PORTLAND",
"region": "ME ",
"country": "USA",
"postalCode": "04106-6226"
},
"phones": [
{
"countryCode": "123",
"areaCode": "987",
"phoneNumber": "1234567",
"phoneType": "Mobile"
}
],
"customerId": 3309843,
"alternateCustomerNumber": "bilbo_1",
"title": "Mr",
"first": "Bilbo",
"middle": "",
"last": "Baggins",
"fullName": "Bilbo Baggins"
},
"payment": {
"paymentMethodCode": "V",
"prePaid": false,
"paymentInstrumentType": "CREDITCARD",
"creditCard": {
"creditCardNumber": "4530910000012345",
"cvnResultCode": "P",
"expiration": "2015-01-01T00:00:00Z"
}
}
}
Scenario 6: orderedBy same as shipTo, authorized with a credit card, ShipRight to handle capture.
In this scenario, a customer orders a product and chooses to pay by credit card. The card is authorized at the shopping cart. ShipRight will capture the payment immediately before the order is processed for shipping. The person ordering is the same person who will be getting the product.
{
"lineItems": [
{
"unitPrice": 1.01,
"itemCode": "COMP CHOCOLATES 1LB",
"quantity": 1
}
],
"alternateOrderNumber": "scenario_6",
"ownerCode": "SR",
"orderClass": "DEFAULT",
"campaignCode": "DEF",
"orderTotal": 1.01,
"tax": 0,
"shippingAmount": 0,
"shipVia": "RG1",
"orderDate": "2014-06-02T16:00:00Z",
"orderSourceId": "5",
"shipToSameAsBillTo": true,
"orderedBy": {
"address": {
"email": "aragorn@rivendell.com",
"address1": "Isuldur",
"address2": "165 Pleasant St",
"city": "South Portland",
"region": "Me",
"country": "USA",
"postalCode": "04106"
},
"phones": [
{
"phoneType": "Mobile",
"countryCode": "123",
"areaCode": "987",
"phoneNumber": "1234567"
}
],
"alternateCustomerNumber": "aragorn_1",
"title": "Mr",
"first": "Elessar",
"middle": "",
"last": "Telcontal"
},
"payment": {
"paymentMethodCode": "V",
"prePaid": false,
"paymentInstrumentType": "CREDITCARD",
"creditcard": {
"creditCardNumber": "4530910000012345",
"cvnResultCode": "P",
"expiration": "2015-01-01T00:00:00Z",
"authorizationDate": "2014-03-12T16:00:00Z",
"authorizationCode": "ac_scen_6",
"transactionID": "76543219"
}
}
}
Scenario 7: Existing customer, standardized orderedBy same as shipTo and pre-paid with a credit card, ShipRight to handle refunds and customer service. In this scenario, a customer orders a product and chooses to pay by credit card. The card is authorized and captured at the shopping cart, but card information is sent with the order so that ShipRight can handle refunds and continuity orders. The person ordering is the same person who will be getting the product and the address is already standardized.
{
"lineItems": [
{
"unitPrice": 1.01,
"itemCode": "COMP CHOCOLATES 1LB",
"quantity": 1
}
],
"alternateOrderNumber": "scenario_7",
"ownerCode": "SR",
"orderClass": "DEFAULT",
"campaignCode": "DEF",
"orderTotal": 1.01,
"tax": 0,
"shippingAmount": 0,
"shipVia": "RG1",
"orderDate": "2014-06-02T16:00:00Z",
"orderSourceId": "5",
"shipToSameAsBillTo": true,
"orderedBy": {
"address": {
"standardized": true,
"email": "aragorn@rivendell.com",
"address1": "ISULDUR",
"address2": "165 PLEASANT AVE",
"city": "S PORTLAND",
"region": "ME",
"country": "USA",
"postalCode": "04106-6226"
},
"phones": [
{
"phoneType": "Mobile",
"countryCode": "123",
"areaCode": "987",
"phoneNumber": "1234567"
}
],
"customerId": 3316351,
"alternateCustomerNumber": "aragorn_1",
"title": "Mr",
"first": "Elessar",
"middle": "",
"last": "Telcontal"
},
"payment": {
"paymentMethodCode": "V",
"prePaid": true,
"paymentInstrumentType": "CREDITCARD",
"creditcard": {
"creditCardNumber": "4530910000012345",
"cvnResultCode": "P",
"expiration": "2015-01-01T00:00:00Z",
"captureDate": "2014-06-02T16:00:00Z",
"authorizationCode": "ac_scen_10",
"transactionID": "765432110"
}
}
}
You can download the accompanying files for JSON samples illustrating these scenarios here. This also includes the responses and an XML version of scenario 1. Once you’ve obtained an API key, the scenarios can all be tested. The easiest way to see the API in action is to use a tool like curl or fiddler. Here’s a curl command to send the JSON request in the file scenario1-request.json to the API test endpoint:
curl -H “SRS-ApiKey: YOUR API KEY” -H “Content-Type: application/json” -X POST -d@scenario1-request.json https://apiplay.shiprightsolutions.com/v1/order -v
See Order Request Fields for request data field requirements.
Payment Objects describes Payment object details and requirements for various scenarios.