1. Documentation /
  2. WooCommerce Marketplace /
  3. SaaS Product Guidelines /
  4. Billing API for SaaS products

Billing API for SaaS products

Introduction ↑ Back to top

The Billing API enables SaaS service providers to sell subscriptions for their software service to WooCommerce Marketplace customers via our in-house billing and subscription system. WooCommerce.com powers the billing relationships between the SaaS provider and the customers using a full-featured subscription and recurring payments solution with support for free trials, upgrades, downgrades, and one-time payments.

If you’re a provider, you need to integrate with the billing API and follow the guidelines described below to get your SaaS product listed in the WooCommerce Marketplace. You can integrate the Billing API with your existing sign-up and purchase flows, or create a different experience specifically for customers coming from WooCommerce.com.

Glossary ↑ Back to top

  • Vendor – SaaS service provider partnering with WooCommerce.com to sell their solution via the WooCommerce.com marketplace.
  • Vendor application (application) – The Vendor’s application, that integrates with the Billing API to communicate with WooCommerce.com.
  • Merchant – WooCommerce.com user, purchasing the SaaS product.
  • Subscription plan (plan) – A subscription product.
  • Subscription contract (contract) – Agreement in which merchant consents to having their payment method charged recurrently in exchange for the service the SaaS Vendor offers.
  • One-time charge (charge) – A one-off (non-renewable) charge.
  • Contract sign-up – A process of creating a subscription or charge contract and getting the merchant’s confirmation of it.

Subscription contract sign-up flow ↑ Back to top

Merchants need to go through the contract sign-up flow to acquire an active subscription to your SaaS plan. Here are the typical steps:

1. Merchant follows a link in a WooCommerce Marketplace listing and lands on the vendor application ↑ Back to top

At this stage, merchants are usually asked to authenticate (sign in or register) in the vendor application, before continuing with the purchase. However, this is not a requirement: we suggest it as a way to bind the subscription contract, to be purchased on WooCommerce.com, with the user account in your application. It’s up to you to decide how to identify the merchant and when to associate them with the contract. You can postpone authentication until after the payment is completed, or skip it entirely.

If you decide to integrate our billing system into existing landing pages and sign-up flows, please ensure that customers coming from WooCommerce.com are distinguished from others: the only available payment method for them is WooCommerce.com’s billing system.

If there are several plans available in your application, you can have the merchant choose one before initiating the purchase. You may also decide to not show the merchant anything and initiate the purchase immediately, as described in the next step.

2. Initiate the purchase ↑ Back to top

Make an API call to WooCommerce.com’s billing API with the subscription plan information. You’ll receive a confirmation URL in the response. Please review the API documentation for more details.

Typical subscription plan information includes the plan name, price, billing period, billing interval, trial period (optional), trial length (optional), and a return URL. The return URL is a URL in your application where we’ll redirect the merchant after they complete the purchase on WooCommerce.com. You can optionally set up a free trial in this step. Please refer to the free trial section below for more details.

The confirmation URL is unique on WooCommerce.com. Your application needs to redirect the merchant to it to confirm and pay for the subscription. The response also contains a unique subscription contract ID in the form of a UUID, which you can use to associate the subscription in our systems with your application’s internal customer ID. Please review the API documentation for more details.

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, the operation will take less than a few seconds to complete. The experience for the merchant is seamless, as if they never left WooCommerce.com.

3. Merchant confirms the purchase ↑ Back to top

The application redirects the merchant to the confirmation URL on WooCommerce.com, where they’ll confirm and pay for the subscription. The merchant goes through a familiar checkout experience, with all the necessary payment information pre-filled if they’ve purchased from WooCommerce.com before.

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

After the merchant confirms and completes the purchase, they are redirected to the return URL you provided in the initiation step. If you haven’t already signed up the merchant, you can do it in this phase. The return URL passes the contract ID in a GET parameter, so you can associate it with your internal customer ID.

WooCommerce.com also makes a webhook call to your webhook URL with the saas_billing_contract.activated topic. This signals that the contract was confirmed and the payment was successful. Please see the webhook section for more details.

Free Trials ↑ Back to top

Our billing system optionally supports free trials. Free trials help reduce the number of refunds and cancelations by allowing merchants to see if the service is a good fit for them before purchasing. You can specify the trial period during the subscription signup initiation phase. Pass the trial_period and trial_length parameters during the initial API call.

We automatically charge the subscription price when the trial period ends if the merchant didn’t cancel the subscription. You will get a webhook call with the saas_billing_contract.renewed topic and the contract details. Please review the webhook section for more information.

Upgrade or downgrade a subscription ↑ Back to top

The Billing API supports subscription upgrades or downgrades. Use this feature for things like changing the billing interval (monthly to yearly, or vice versa), switching to a more expensive or cheaper subscription.

A prorated amount is automatically calculated on WooCommerce.com following the logic described in the Subscription Switching Guide. You can override this amount using the prorated_amount parameter in the API call. The typical flow is described below.

1. Initiate the switch ↑ Back to top

Initiate a subscription switch using the POST /subscriptions/{contractID} endpoint. Provide all of the necessary information, as described in the API documentation. There will be a confirmation_url in the response. Redirect the merchant to this URL so they can confirm the switch and pay any prorated amount. Please see the API documentation for more details.

2. Merchant confirms the switch ↑ Back to top

The merchant lands on WooCommerce.com to confirm the switch. If a prorated amount is due, or if one was passed in the previous step, they’ll need to pay to complete the switch. If the new subscription is cheaper (a downgrade) they’ll be credited for the difference by having their subscription extended.

3. Merchant is redirected to your application ↑ Back to top

Once the merchant confirms the switch, the subscription is updated on WooCommerce.com and they are redirected to the return URL you provided in the initiation phase. The contract id is appended to this URL as a GET parameter. This is a good time to update their subscription in your systems. WooCommerce.com also makes a server-to-server call to your webhook URL with the saas_billing_contract.updated topic. The webhook request body contains the contract object. Check out the webhook section for more details.

One-time charges ↑ Back to top

The Billing API also supports one-time charges. This feature can be used to charge merchants for things that are not renewable. For example, say you’re offering email delivery services and you want to offer credit packs to your customers to use during promotions, or whenever they need an extra boost. These don’t incur recurring charges and can be purchased as needed. The typical one-time charge flow is very similar to the subscription signup flow and is described below.

1. Initiate the charge ↑ Back to top

Initiate a charge by calling the POST /charges endpoint. Provide the necessary information as described in the API documentation. The response will have a confirmation_url. Redirect the merchant to this URL. See the API documentation for more details.

2. Merchant confirms the charge ↑ Back to top

The merchant lands on WooCommerce.com and confirms the charge details. Once they complete the payment, they’re redirected to the return URL you provided in the initiation phase.

3. Merchant is redirected to your application ↑ Back to top

The merchant is redirected back to you via the return URL. The charge contract id is appended to this URL as a GET parameter. This is a good time to add the product they paid for to their account. WooCommerce.com also makes a server-to-server call to your webhook URL with the saas_billing_contract.activated topic. The webhook request body will have the charge object. Please review the webhook section for more details.

HTTP API ↑ Back to top

API reference ↑ Back to top

API reference documentation: https://woocommercecomsaasbillingapi.docs.apiary.io/

You can download the OpenAPI specification file from the documentation link above and use it with any tool that supports this standard. For example, you can import it in Postman to get a ready-to-use collection of requests.

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 is issued a set of credentials (API key and secret) during onboarding. To authenticate API requests, you need to use the Basic authentication method and pass the following HTTP header with your request:

Authentication: Basic base64encode(api_key:api_secret)

Here’s an example of a POST request to the /subscriptions endpoint to initiate a plan purchase (please replace ENCODED_KEY_SECRET_STRING with your own secret key):

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

The integration with the SaaS Billing API should be implemented and tested inside the sandbox, before being opened up for production usage. The differences between production and sandbox are the domain (sandbox.woocommerce.com) and the API credentials. Switching from sandbox to production should just be a matter of changing the domain name, API key and secret.

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

Your integration with the WooCommerce.com billing system goes through a technical review before the SaaS product can be listed in the marketplace. Once your integration with the WooCommerce.com sandbox is ready, please send us a link where we can test it so we can confirm everything’s working great. It doesn’t need to be your live environment, but it should be a working example that can be accessed by our technical team for review.

Webhooks ↑ Back to top

We support sending notifications to your application on certain events, such as contract activation for both subscriptions and charges, subscription renewals, successful subscription upgrades or downgrades, and contract cancelation. The contract object is always included in the body of the webhook request. A typical request body payload looks like this:

// example of a subscription contract
{
  "subscription": {
    "id": "9964455a-bf9f-4a36-8023-b307a3b6e715",
    "status": "active",
    "billing_intents": [
      {
        "id": 1,
        "status": "completed",
        "payload": {},
        "created_at": "2021-12-01",
        "update_at": "2021-12-01"
      }
    ]
  }
}

// example of a one-time charge contract
{
  "charge": {
    "id": "9964455a-bf9f-4a36-8023-b307a3b6e715",
    "status": "active",
    "billing_intents": [
      {
        "id": 1,
        "status": "completed",
        "payload": {},
        "created_at": "2021-12-01",
        "update_at": "2021-12-01"
      }
    ]
  }
}

As you can see, we don’t share merchant information via webhooks. They are primarily used to notify you, the vendor, about various changes in the lifetime of a contract. The request payload includes the contract ID, status, and any billing intents. The event that triggers the webhook call is delivered in the form of a topic and can be found in the x-wc-webhook-topic request header.

The topics that are currently available are:

  • saas_billing_contract.activated – This event is triggered when a merchant successfully confirms a subscription or one-time charge. This indicates the contract is paid for and active. You can use this event to activate their plan or feature.
  • saas_billing_contract.updated – This event is specific to subscriptions. It’s fired when a merchant successfully confirms a plan upgrade or downgrade and pays the prorated amount (if any). The contract status is active. You can use this event to update their plan in your system.
  • saas_billing_contract.renewed – This event is also specific to subscriptions, and is fired when a successful subscription renewal occurs. This event indicates that the merchant was successfully charged the renewal amount. The contract status is active.
  • saas_billing_contract.canceled – This one is fired when a subscription or one-time charge is canceled. Use this to deactivate a merchant’s plan or feature. Please note that charges can only be canceled before they are confirmed by the merchant. You as the vendor can also cancel contracts using the corresponding DELETE calls as described in the API documentation. The contract or charge included with the webhook call will have the canceled status.

The request body payload is signed with the API secret and the signature is included with the X-WC-Webhook-Signature request header. You can use the signature to confirm the integrity of the payload.

An example of PHP code to make the 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;
}

To enable webhook notifications, you need to provide a URL in your application that accepts webhook requests. The URL must be publicly accessible, with no authentication or IP whitelisting. We currently support one webhook endpoint per application. You can add, update, or remove the application’s webhook URL in your SaaS application settings.

Renewals ↑ Back to top

Renewals are handled by WooCommerce.com. They are automatic and hands-off for merchants. The experience is similar across all products sold through the WooCommerce Marketplace.

Your application needs to support automatic renewals, so please make sure the merchant isn’t required to take any manual action for the renewal to occur.

Use the webhook system to get notifications about successful renewals, so you can keep their subscription going on your end.
WooCommerce.com will email merchants before and on the day of the renewal. Feel free to send any renewal-related communication of your own to them as well.

Subscription cancelations and refunds ↑ Back to top

Merchants must be able to cancel a subscription from your application, so please make sure that feature is implemented. There is a dedicated endpoint in the HTTP API to cancel contracts. Please review our API documentation for the DELETE endpoints.

Refunds are not possible on subscription cancellations. If the merchant cancels the subscription, the expectation is that they’ll benefit from their current plan until the end of the prepaid period.

For example, if a yearly subscription is canceled after 3 months the merchant will benefit from your service for the remaining 9 months.
What you do with the merchant account in your application after they cancel their subscription is up to you.

SaaS application settings ↑ Back to top

As a vendor, you can view and edit your SaaS application settings. You need to register a user if you don’t already have one. Once you have a user, please share the email address used during registration with us, so we can link it with the vendor. After this set up you’ll be able to login into your vendor dashboard and access your SaaS application settings.

Navigate to SaaS Apps to view the list of applications. You’ll likely have only one.

View your SaaS applications

To access the application’s settings, click on the API key. On the settings page, you can view and copy your API key and secret, generate a new API key & secret pair, and add/edit/remove the webhook URL associated with your application.

View/edit your SaaS application settings.

SaaS webhook testing tool ↑ Back to top

This tool is only available on the sandbox to help with the integration step. This is not available in production as it has side effects for payments, user communication, subscription status, etc. The purpose of this tool is to help you, the vendor, test your webhook integration in an easy, repeatable way.

To use the webhook testing tool, log into your vendor dashboard on sandbox.woocommerce.com and navigate to SaaS Apps > Webhooks.

Input any contract UUID you’d like to test webhook calls against in the form and hit enter or click on Select for testing. The page will reload with the contract selected. You can trigger webhook calls for the selected contract by clicking on the appropriate event button on the page. Please note that the available events depend on the current contract status. The webhook call is triggered async, so it may take up to a minute to receive the call. You can read more about the available webhook events in the webhooks section of this documentation. Make sure you have a webhook URL set up in your SaaS Application settings.

Questions & answers ↑ Back to top

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

Not at the moment. Only USD is currently supported. We’re considering adding other currencies like EUR or GBP, but there’s no ETA on this.

How are taxes handled? ↑ Back to top

To comply with the merchant’s local regulations, we add tax on top of the original price. The tax amount will vary depending on the merchant’s country of residence and will be calculated automatically. You can add a notice about this in your application, to let merchants know that the total may be different due to tax.

There’s no reliable way to confidently calculate tax in advance before the merchant lands on WooCommerce.com and submits their billing details. There are many factors that determine the tax calculation. This makes it impossible to make a correct prediction without having all the necessary data upfront (such as billing address, IP address, validated VAT ID, and others).

Do my application and WooCommerce.com exchange merchant personal information? ↑ Back to top

No, we don’t share personal details, such as email, name, or address with the vendor application. And we don’t expect you to either. The flows are designed to work without exchanging personal information. So, if you need any personal data from the merchant, you can request it from them during sign-up.

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

You can map them using the unique contract ID that’s appended to the return URL the merchant is redirected to after a successful purchase.
The billing API and webhooks also use this ID to identify the subscription. There’s no need to use personal information to map merchants to purchases.

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

Getting listed on the WooCommerce.com Marketplace enables software vendors to offer their products to a wide audience of millions of registered users. As with any other marketplace, you need to follow some guidelines and requirements to get your product listed. This improves the overall quality and experience for customers, which is why they choose to purchase through us rather than from software vendors directly.

That being said, these requirements don’t apply to all of your customers, only those coming from WooCommerce.com. You’re free to use your current billing system and flows for your existing customer base, or customers coming from sources other than our 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