How to write a bespoke ecommerce store integration to Penny Black
An ecommerce store integration to Penny Black provides the order information used to segment and personalise PDFs for printing. It is the primary data that drives all of Penny Black.
We offer a variety of ready-to-use integrations for many popular ecommerce platforms, making it easy to get started. If your platform is not yet integrated, just reach out to us at support@pennyblack.io, and we'll add your request to our product roadmap.
Alternatively, for those with custom-built or unsupported platforms, you can seamlessly integrate your store into Penny Black by making API calls to our ingest services.
Prerequisites
To get started you'll need a sandbox merchant account and an API key.
Create a Penny Black sandbox account
Anyone can sign up for a Penny Black account.
- Go to app.pennyblack.io/register and sign up as a new user
- After signing up you will see the Connect Store screen
- Choose Other
Fill in the details for your store, indicating that it's a test store both in the name and by checking the Test Store tick box:
If you already have a production account use a different email address to register and create a sandbox account or contact our support team
Get your API key
The API key will be immediately available once you log in as part of the setup stage:
It can also be found at any time in future on the Settings page. Go to the E-COMMERCE tab and you will see it in the Platform section:
Once you have your API key you are all set for making requests. Remember that you'll need to use the separate API key for your production store account when you have completed the integration and are ready to launch.
Integration overview
There are two main API endpoints for a basic integration to Penny Black:
- install store - this request should be sent initially to register your store URL with Penny Black. This is usually called once as part of a platform plugin or extension install process. You could hook this into your own feature toggling system, or just call the API manually once to save time.
- send order - used to transmit each order that is placed in your store to Penny Black
Sending orders
The order-sending API call should be hooked into relevant order events in your platform so that orders are automatically sent to Penny Black as close to the confirmed checkout time as possible.
The API page indicates which fields are required, and the majority are optional. We recommend supplying as much of the information as possible to give you flexibility to build any segment you might want, and to likewise add any kind of personalisation data that you want to your inserts.
However, if you know that some information won't be used, is difficult to extract or low quality then feel free to omit it.
We do not support updating orders at this time. If orders are commonly modified in a way that could impact Penny Black then you might want to consider delaying sending orders until they are more stable. Duplicate orders will be ignored.
Transmission timing
We recommend sending orders as soon as possible so that a PDF is generated and ready before the order needs to be packed. Whilst our processing of orders is fast, it is sometimes necessary to add a processing delay if you are enriching data from third-party systems such as Emarsys or Klaviyo after order ingest. We have added delays of up to 20 minutes before to cater for other systems completing their tasks to ensure data is available.
If this is not applicable to you, your pack times are not immediate, then transmitting orders immediately is less of a concern.
Debugging orders
Once you have transmitted an order you can see it immediately on the Activity page:
Click on the order number to open an overlay with the full order details for comparison.