API Reference

Testing Your Integration

Some guidance on setting up an end-to-end testing platform for your local shopper experience

Using a Test API Key

Your account manager will provide you with an API key prefixed by test_*. Or you may generate a test key in Locally's "Station" web portal by following these instructions (select the option for creating a test key).

Using this key will allow you to create "virtual" carts for any of the stores in your dealer network. These carts are great for end-to-end testing purposes and will not affect or be detectible by retailers in any way.

Test Cart Scenarios

When you use a test_* key, the following behaviors will differ from standard, live production flows:

  • Carts & Cart Items:
    • These carts are only accessible by your own Cart API requests.
    • Retailers are unable to see or access these carts via API or web console.
    • Webhooks related to add-to-cart events will not be sent to any parties.
  • Processing Cart Transactions:
    • Payment authorizations, fund captures, refunds, partial refunds and sales tax captures will be made against a decoy payment service provider (PSP), instead of the retailers production PSP.
    • Sales tax estimates will not be committed.
    • No commissions related to the sale will be charged to retailers.
    • No retailer inventory deprecation will occur upon the confirmation of a cart item.
    • Time-based post-order automations, such as auto-cancelations and stale order reminders, are disabled for all test orders.
  • Communications
    • No SMS and Email communications will be sent to the retailer, however you may configure a specific email address and/or SMS number to use for mocking the retailer's own email and/or mobile device. To set a test email and/or SMS number, please use the "Test Connectivity" tab in the webhook configurator in Locally's web portal.
    • SMS and Email communications will only be sent to the shopper email/SMS that was defined in the API requests.
    • All webhooks related to activities in the cart's lifecycle will be sent to the endpoint specified in the "Test Connectivity" tab of the webhook configurator.
    • All subscribers to the webhooks of the retailer's point-of-sale system will not receive webhook payloads for any event related to an activity in the cart's lifecycle.

Example Request

Note the use of Locally-Api-Token header containing the test_* prefixed key. 

curl --request POST \
      --url https://www.locally.com/headless/api/1.0/cart/validate \
      --header 'Content-Type: application/json' \
      --insecure \
      --header 'Locally-Api-Token: test_abc123' \
      --data '{
    "card_token": "seti_1PCXykAAKdQR3wItTnMmgimR",
    "host_domain": "www.example.com",
    "path_to_purchase": "bopis",
    "store_id": 37175,
    "mute_comms": 1,
    "items": [
        {
            "upc": "686487455948",
            "qty": 1,
            "price_per_unit": 225.00,
            "tax_per_unit": 0.07,
            "message": "This is a message for the store"
        },
        {
            "upc": "686487455955",
            "qty": 1,
            "price_per_unit": 225.00,
            "tax_per_unit": 0.07,
            "message": "This is another message for the store"
        }
    ],
    "shopper": {
        "email": "test@example.com",
        "phone": "+10000000000",
        "first_name": "Chester",
        "last_name": "Copperpot",
        "address": "24 Moon Drive",
        "city": "Mars",
        "state": "AL",
        "zip": "28704",
        "country": "US",
        "is_opt_in_consent": "0",
        "is_opt_in_consent_brand": "0"
    }
}'

Example Response

Responses and webhooks for test carts will all include the is_test parameter. Here is an example webhook payload that was sent after a order was committed:

{
  "upc":"686487455948",
  "order_id":"4XV",
  "status":"ordered",
  "for_ship_to_store":0,
  "is_test":1,
  "order_url":"https://www.locally.com/api/v2/cart/4XV"
}