API Reference

Purchase POST

This composite endpoint facilitates the creation of subscriptions, addresses, payments and customers with a single POST.

  • Can be used with, without and at the same time as OrderGroove's cart tracking system.
  • POST must be made to OrderGroove with every purchase/checkout regardless of whether or not a subscription is to be created.
  • If subscription information is being sent, Payment becomes a required object in the payload. If a subscription is not being created with the transaction you may omit the payment object.

The customer, address, and payment information given will be matched to existing customer records, so there
should be no concerns around duplicating customer information on repeat requests. Some fields listed
as optional here can actually be required working with your OrderGroove specialist(s).

URL

Because this endpoint handles payment information, it uses a different host: https://sc.ordergroove.com.

Authentication

Purchase Post: You will still use customer scope for this endpoint. The customer id to use is that one you're about to create.

Subscription Response: Retrieving the subscription creation response requires api user scope for this endpoint.

Request Body

This POST body is different from all the other post bodies. It's not a simple JSON object, but an HTTP Form body where the only field sent is called create_request and its value is a JSON string of the object. For example:

In javascript, you can do using the request http client:

import request from 'request';

const payload = {
  merchant_id: 'test merchant',
  session_id: 'session identifier',
  merchant_order_id: 'order ID associated with the purchase'
  // ...etc...
};

// the payload must also be url encoded.
const json = encodeURIComponent(JSON.stringify(payload));

request({
  url: 'https://sc.ordergroove.com/subscription/create/',
  body: `create_request=${json}`
});

The body will look like:

create_request={
  "merchant_id": "test merchant",
  "session_id": "session identifier",
  "merchant_order_id": "order ID associated with the purchase",
  ...etc...
}

Note that even though the body is a form body, the content-type for your request should still be application/json.

Asynchronous

Our standard integration proccesses Purchase Post requests asynchronously. Some of the data provided will however be validated before the response.

If there are any errors, they will be found in the errors object of the response. Some examples:

400 - no records will be created
{"error": "Invalid Merchant MERCHANT_PUBLIC_ID"}
{"error": "Merchant ID must be a string"}
{"error_message": "Merchant order id cannot be null"}
{"error_message": "Session id cannot be null"}
{"error_message": "Session ID must be a string"}
{"error_message": "Missing payment data to create record"}
{"error_message": "The credit card encryption is not valid"}
{"error_message": "Expiration date is not valid, received: "}
{"error_message": "Paymetric tokenization error"}

If there are no errors, the response will contain an object with a field called subs_req_id. The value of this field can be used to retrive the result of this operation later using the Subscription Response endpoint described below.

Synchronous Response Body

This workflow has been deprecated please contact your solutions specialist if you are or would like to use synchronous processing. Given the amount of data being provided and the order in which the contents of the payload are validated and created, there will be instances where a 400 or 207 status will be returned, but the customer,
shipping, and payment OrderGroove ids will be provided as they were created, even though there may
have been an issue with some or all products provided in the request.

If there are any errors, they will be found in the errors object of the response. Some examples:

400 - no records will be created

{"errors": {"session_id": "Session ID cannot be null."}}
{"errors": {"user_id": "User ID is a required field."}}
{"errors": {"products": "Products is a required field."}}

{
  "errors": {
    "customer": {
      "first_name": ["first_name is a required field"],
      "last_name": ["last_name is a required field"],
      "email": ["email is a required field"]
    }
  }
}

207 - Partial record created

{
  "customer": "aab98a89as0989",
  "payment": "f67a4sd564654s",
  "subscriptions": [{
    "some_product_id": "68b78786s78d6f",
  }],
  "errors": {
    "products": [{
      "sku is a required"
    }],
    "subscriptions": [{
      "product": "faux-product",
      "subscription": {
        "product": ["Object with external_product_id=faux-product does not exist."],
        "quantity": ["This field is required."]
      }
    }
  ]
}