Developers can use OxeBox generateBill API to dynamically generate PDF bill receipts and send it to customer email. OxeBox API solves two major problems faced by the developers:


1) Zero integration with any PDF library: Creating PDF sale receipts involves setting up the third-party library and can be time-consuming. OxeBox API automatically creates PDF receipts with sales data.


2) Zero integration with any ESP: Receipts sent to customers email from your own servers often land in users' SPAM folder due to poor server reputation, and using a dedicated ESP (Email service provider) service to send emails is a costly affair. OxeBox API uses best-in-class infrastructure to make sure your email receipts are delivered to user INBOX.


Follow this guide to start using OxeBox API:


Step 1: Sign-up as a developer

Register here to create a new developer account on OxeBox. Upon successful signup, you will be emailed the PartnerID, BusinessID, and AuthKey, which are required for API integration.


Step 2: Integrate OxeBox API

Once you have the Partner-ID, BusinessID, and AuthKey you are ready for integration. OxeBox API can be practically integrated with any programming language capable of making the HTTP request. At what point of time you should invoke API to generate bill depends on your business needs, but in most of the cases, it will be when a sale is happening.


To generate a new bill you would require the following details:

  • HTTP Request Method: POST
  • HTTP API Endpoint: https://www.oxebox.com/pbrapi/alpha/v1/index.php/PBR/generateBill
  • HTTP Header: Every API request MUST include the PartnerID and API Key in the HTTP request header. You can find header details here.
  • Body: The payload data is in JSON format and contains sales information like customer details, billing details etc. The payload must be JSON encoded. You can find the structure of payload JSON here.


The payload contains following sections:

  1. TemplateDetails - Name of the template which defines what format/layout the receipt will be generated in. Default template name is DEFAULT_TEMPLATE
  2. CustomerDetails - This section different customer details, like customer name, email address, phone number and country code etc. You MUST provide either customer email address or phone number to send bill receipt to the customer account.
  3. PartnerDetails - Partner details section contains PartnerID and AuthKey provided to you during registration purpose and its needed for tracking purposes.
  4. StoreDetails - In this section, StoreID key contains BusinessID which is emailed during the signup process. If you have more than one stores, BusinessID will be used to identify for which store bill is generated and to fetch the correct store details like address, name, logo etc.
  5. BillingDetails - This section contains all the sales data like item price, description, quantity, taxes and discounts, additional charges etc.


Step 3: Customize OxeBox Dashboard

Once you have integrated OxeBox API with Point of Sale/Website/Backend its time to complete profile details and customize the bill via OxeBox Dashboard. Details updated in the dashboard will be sent as part of every bill receipt generated. 


Login to OxeBox Dashboard with the registered email address (password sent with the welcome kit), navigate to the profile and customization sections and update available fields.


1) Profile Section: This section contains basic profile details like Business Name, Business Logo, Address, Phone number and Tax related details.

2) Customization Section: In this section, you can configure what store promotional content goes as part of every bill. You can configure promotional offers, provide embed-link to Store videos or enhance the receipt with different social media handles like Facebook, Instagram, Twitter or Youtube


Before you start sending bill receipts, It's important to understand OxeBox bill receipt components. Every OxeBox bill has two components


1) Static content: The static content of the bill receipts comes from OxeBox Dashboard. OxeBox dashboard needs to be configured with details like store name, address, header & footer text and promotional details. For every bill generated for this particular store, these details remain the same and picked from OxeBox dashboard. This section of the bill will remain constant until changes are made to OxeBox Dashboard.


2) Dynamic content: The dynamic content or billing part of the receipts comes from the JSON data that is sent to OxeBox whenever a sale is happening. This data contains information about what items are sold, unit price, taxes and discounts and other details. This section of the bill will change whenever a new sale happens.



Step 4: Start Sending Digital Receipts

Now that you have customized OxeBox dashboard with store specific details and enabled promotional features, its time to test the OxeBox bills. Make a test sale on your website or POS terminal and see if the bill can be successfully generated.

Analyzing the API response for error details can be a good starting point for troubleshooting. If a bill is generated successfully,  a link to the bill is returned in response["data"] section. If the API response["status"] is error, check the response["message"] contents to find out details about what went wrong.


Sample API Response:

{
  "message": "Bill receipt successfully sent to mobile: 9871XXXXXXXX",
  "status": "success",
  "data": "https://oxebox.com/a/C5eTiOHk4Ob"
}

Some common errors could be Payload data is not JSON encoded, invalid AuthKey and PartnerID, or both email address and Phone number fields missing in CustomerDetails section


Few ways you can check if Oxebox bill is generated are:

  • Login to the OxeBox Dashboard with your registered email address, navigate to OxeBox Bills section and see if the bill you just generated is available or not.
  • Download and register on OxeBox mobile app (Android | iOS) with the mobile number and email where OxeBox bill is sent, the bill should be listed there.
  • If customer email address is provided in customer details section, check if the PDF bill receipt is sent to this email.


Please check the FAQ section or write us at support@oxebox.com if you have any questions or suggestions.