1. Documentation
  2. Plugins
  3. WooCommerce
  4. WooCommerce Marketplace

Billing API for SaaS products

Introduction ↑ Back to top

SaaS Billing API enables SaaS providers to sell subscriptions for their software service to WooCommerce Marketplace customers through its in-house billing and subscription system. WooCommerce.com will power billing relationships between the SaaS provider and the customers, providing a fully-featured solution for subscriptions and recurring payments with the support for free trials, upgrades, downgrades and one-time payments.

Providers need to integrate with the API following the guidelines below to get the SaaS product listed in the WooCommerce Marketplace. It is possible to integrate the Billing API with the existing sign-up and purchase flows, or create a different experience specifically for customers coming from WooCommerce.com.

Glossary ↑ Back to top

  • Vendor – SaaS provider partnering with WooCommerce.com for selling their product.
  • Vendor application (application) – vendor’s SaaS application, communicating with WooCommerce.com via HTTP API.
  • Merchant – WooCommerce.com user, purchasing the SaaS product.
  • Subscription plan (plan) – subscription product
  • Subscription contract (contract) – merchant consent for recurring charge for subscription plan.
  • Contract sign-up – a process of creating a subscription contract and getting merchant’s confirmation for it.

Contract sign-up flow ↑ Back to top

Merchants need to go through the contract sign-up flow in order to acquire an active subscription for your SaaS plan. The typical steps are described below:

At this stage, merchants are usually asked to authenticate (sign in or register) in the vendor application, before continuing with purchase. However, we don’t necessarily require the merchant to authenticate in your system – it is only suggested as a way to bind the subscription contact, purchased on WooCommerce.com, with the user account in your application. It’s up to you to decide how to identify the user and associate it with the contract. Authentication can be skipped or postponed to a later stage (after the payment received).

If you decide to incorporate WooCommerce.com’s billing into the existing landing and sign-up flow, used for all your customers, you must ensure that customers coming from WooCommerce.com are distinguished from customers arriving from other sources, and the only available payment method for them is WooCommerce.com’s billing system.

If there are several plans available in your application, you may show them to the merchant to choose from. You may also decide to not display anything to the merchant and immediately follow to the next step (purchase initiation).

2. Purchase initiation ↑ Back to top

The application submits a server-to-server request to WooCommerce.com with the details of the subscription plan for purchase and return URL, and receives a confirmation URL in the response.

Typical details of the subscription plan are name, price billing period and interval, trial period and length. The return URL is an endpoint in your application, where the merchant will be redirected after a successful purchase on WooCommerce.com.

Confirmation URL is a unique URL on WooCommerce.com, which the merchant needs to be redirected to in order to confirm the subscription. Additionally, the response will contain a unique subscription contract ID, which can be associated with the application’s internal customer ID.

If you initiate the purchase immediately when the customer lands on the application, and then redirect to WooCommerce.com confirmation URL during the same request, it will take less than a few seconds in total. Thus, merchant may not even notice that they were leaving WooCommerce.com.

3. Purchase confirmation ↑ Back to top

The application redirects the merchant to the confirmation URL on WooCommerce.com, where they confirm the subscription contract. The merchant goes through the familiar checkout experience, with all the necessary payment information pre-filled if they already purchased from WooCommerce.com before.

4. Merchant gets redirected to your application ↑ Back to top

After the merchant confirms the purchase and the charge is successful, they get redirected to the return URL in your application.

If the merchant was not authenticated in the application before, they can be offered to do that at this stage. The return URL contains the contract ID within a GET parameter, so it would be possible to associate it with your internal customer ID.

Additionally, WooCommerce.com sends server-to-server request to vendor’s webhook URL to notify your application directly about successful contract payment.

HTTP API ↑ Back to top

API reference ↑ Back to top

API reference documentation: https://woocommercecomsaasbillingapi.docs.apiary.io/
The API specification file in Open API format can be downloaded from the documentation page and then used in a variety of tools supporting Open API. For example, you’ll be able to get a ready-to-use collection of requests in Postman by importing the specification file.

Please note that all paths in the reference documentation are relative to the base URL. For example, the /subscriptions endpoint will be resolved into the full URL https://woocommerce.com/wp-json/wccom/billing/1.0/subscriptions

Authentication ↑ Back to top

Each vendor application gets a set of credentials (API key and secret) for authorisation, issued during onboarding. To authenticate API request, you need to use Basic authentication method and pass the following HTTP header with your request:

Authentication: Basic base64encode(api_key:api_secret)

An example of the request to POST /subscriptions endpoint to initiate plan purchase (please replace ENCODED_KEY_SECRET_STRING with the corresponding value):

curl --request POST \
  --url https://sandbox.woocommerce.com/wp-json/wccom/billing/1.0/subscriptions \
  --header 'Authorization: Basic ENCODED_KEY_SECRET_STRING' \
  --header 'Content-Type: application/json' \
  --data '{"name": "test plan", "price": 199.99, "billing_period": "year", "billing_interval": 1, "return_url": "https://example.com"}'

Sandbox for testing ↑ Back to top

Integration with SaaS Billing API should be implemented and tested with the provided sandbox, prior to being opened up for production usage. The difference between the production and sandbox is the domain (sandbox.woocommerce.com) and API access credentials, which are different for each environment. Switching from sandbox to production in your application should be a matter of changing the domain name and API key and secret pair.
Sandbox domain: https://sandbox.woocommerce.com/
Base URL for API on the sandbox: https://sandbox.woocommerce.com/wp-json/wccom/billing/1.0/

Technical review ↑ Back to top

The application’s integration with WooCommerce.com billing system needs to go through a technical review before getting the SaaS product listed on the marketplace. Once your integration with the WooCommerce.com sandbox is ready, please send us a link where we can test and confirm everything works great on both ends. It doesn’t necessarily need to be on your live environment, but it should be a working example, which can be accessed by our technical team for review.

Webhooks ↑ Back to top

We support sending notifications to your application on such events as contract set up, renewal, upgrade, cancelation and other. On every such event, the contact status is updated, which is reflected in the webhook payload.

We don’t use webhook request to deliver personal customer details. Webhook is primarily used for getting notified about the update of the subscription contract status.

The request payload includes only the subscription contract ID and its latest status, without additional information about the event.
An example of a typical payload:

{
  "subscription": {
    "id": "9964455a-bf9f-4a36-8023-b307a3b6e715",
    "status": "active"
  }
}

Payload will be signed with the API secret and included with the request in HTTP header X-WC-Webhook-Signature. You may use the signature to confirm the origin of the incoming webhook request.
An example of PHP code to make such validation:

$api_secret = 'YOUR_SECRET';
$payload = $_POST;
$provided_signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'];
$valid_signature = base64_encode( hash_hmac( 'sha256', $payload, $api_secret, true ) );

if (hash_equals($valid_signature, $provided_signature)) {
    $request_origin_confirmed = true;
} else {
    $request_origin_confirmed = false;
}

For enabling webhook notifications, you will need to provide a URL of the endpoint in your application for accepting webhook requests. As webhook requests are sent from our servers directly, the URL needs to be a publicly accessible, without authentication or IP-whitelisting. Only one webhook endpoint per application is possible.

Renewals ↑ Back to top

The renewals will be handled by WooCommerce.com. They are automatic and hand-off for merchant, which is similar to customer experience across all products sold through WooCommerce Marketplace. Your application needs to support automatic renewals, ensuring there is no manual action required by your application from the merchant.

To have your application notified about the renewal event, so that you could update the subscription on your side based on whether renewal was successful or not, please use the webhook system.

Customers will be notified by email from WooCommerce.com before and on the date of renewal. You may send any kind of communication about renewal from your side as well.

Subscription cancelations and refunds ↑ Back to top

You need to implement ability for customers to cancel the subscription from within your application. There is a dedicated endpoint in the HTTP API for subscription contact cancelation (DELETE /subscriptions/{contractID}).

We do not provide refunds on subscription cancellations. This means that if the customer cancels the subscription, they will still have their current plan active until the end of the prepaid period. Thus, it’s expected that you continue to provide the service until the prepaid period ends.
For example, if a yearly subscription was cancelled after 3 months, there will still be 9 months left for the merchant to use your service.

We don’t set any rule on what to do with the merchant account in your application on subscription cancelation. You may delete or leave the account for the customer, if you prefer.

Questions & answers ↑ Back to top

Is there support for multi-currency? ↑ Back to top

No. At the moment, the only supported currency is the United States dollar. Other world currencies, such as Euro or British Pounds, may be considered to be added in the future, but there is no ETA on this.

How are taxes handled? ↑ Back to top

We add a tax on top of the original price, for compliance with customer local jurisdiction regulations. Customers will be charged the correct tax amount depending on their country of residence. You may add a notice about that in your application to let users know that the total amount during checkout may be different due to extra tax charged.

There is no way to provide the tax calculation in advance, before a customer lands on the checkout page on WooCommerce.com and submits their billing details. There are many factors influencing the tax amount, which are impossible to predict without having all the data, such as billing address, IP address, validated VAT ID, and others, in place.

Does my application and WooCommerce.com need to exchange personal details of the customer? ↑ Back to top

No, we don’t share personal details, such as email, name or address with the vendor application. And we don’t require that information from the application, too. The flows are designed to work without exchanging these details. If you need any personal data from the merchant, you can request them from them before or after the purchase on WooCommerce.com.

How do I map a customer with their subscription on WooCommerce.com? ↑ Back to top

You will be able to map a customer in your application with their subscription on WooCommerce.com by the unique subscription contract ID, which is returned in response to a contract sign up initiation request and, additionally, appended as a GET parameter to your application’s return URL, which the customer is redirected to after payment completed on WooCommerce.com. This subscription contract ID is also used in the HTTP API and by the webhooks to identify the subscription. There is no need to use personal information, such as email, for mapping customers.

Do I need to apply billing requirements to all customers? ↑ Back to top

Listing on WooCommerce Marketplace allows software vendors to offer their product to millions of WooCommerce.com registered users. As any other marketplace, there is a set of requirements and guidelines that need to be followed in order to get the product listed. This ensures the quality and best customer experience and is one of the reasons customers choose to purchase through the Marketplace rather than from software vendors directly.

However, requirements for the SaaS Billing API integration do not need to be applied for all your customers. You are free to follow your current billing patterns for your existing customers or customers coming from other sources than WooCommerce Marketplace.

WooCommerce - the most customizable eCommerce platform for building your online business.

  • 30 day money back guarantee
  • Support teams across the world
  • Safe & Secure online payment