Skip to content
/Payments

Public API Reference (2025-07-30)

The Zephr Public API provides common client-side actions tied to a session cookie. Unlike the Admin API, neither users nor other resources can be dereferenced; the only data that can be accessed is owned by the user who is currently signed-in. This design is used to protect other users from malicious attacks.

You can find the base URL for the Public API by navigating to your site domains. To do this, select Sites from the Delivery menu, select your site, and then click the Site Domains button. The base URL is the Live domain.

Zephr forms use the Public API by default, with relative URLs based on the base URL.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Mock server
https://developer.zuora.com/_mock/zephr-api-reference/zephr-public-api
https://{your-domain}

Authentication

Operations

Braintree Payments

Operations

Browser Feature Transformations

Operations

Decision Engine

Operations

Dynamic Offer Decision Engine

Operations

Dynamic Offer Promo Code Decision

Operations

OAuth Flow

Operations

Payments

Operations

Start the subscription

Request

Uses the payment info captured by the payment provider drop-in UI and create a customer with a recurring payment. When the payment provider responds successfully, the logged-in user will be temporarily granted all entitlements in the product's associated bundle.

Security
CookieBlaizeSession or JwtQuery or JwtHeaderXBlaizeJwt or JwtHeaderXZephrJwt or JwtBearer or JwtCookie
Headers
cookiestring

The session cookie.

Example: `blaize_session=...` (string)
Bodyapplication/json
product_idstringrequired

Product ID/slug

Example: "premium-access-monthly-recurring"
plan_idstring

Plan ID/slug

Example: "plan-5"
discount_codestring

Discount/promotion code

Example: "SAVE10"
vendor_fieldsobject

Parameters specific to the payment provider in-use.

Example: {"payment_nonce":"eyJ2ZXmsaW5nQW...(lots more random-looking characters)...dyZWmVubW8iOiJvZmYifQ==","skip_trial_period":true,"start_date":"2021-01-01T00:00:00Z","payment_method":"pm_123456789","vault_payment_method":false}
curl -i -X POST \
  https://developer.zuora.com/_mock/zephr-api-reference/zephr-public-api/zephr/subscribe \
  -H 'Content-Type: application/json' \
  -H 'cookie: `blaize_session=...` (string)' \
  -b '`blaize_session=...` (string)' \
  -d '{
    "product_id": "premium-access-monthly-recurring",
    "plan_id": "plan-5",
    "discount_code": "SAVE10",
    "vendor_fields": {
      "payment_nonce": "eyJ2ZXmsaW5nQW...(lots more random-looking characters)...dyZWmVubW8iOiJvZmYifQ==",
      "skip_trial_period": true,
      "start_date": "2021-01-01T00:00:00Z",
      "payment_method": "pm_123456789",
      "vault_payment_method": false
    }
  }'

Responses

OK

Bodyapplication/json
grant_idstring

New grant of product bundle to user.

Example: "33d576c7-d036-40e7-8141-8a91998a5c79"
client_secretstring

(Stripe) reference to Stripe payment required to process payment in front end.

Example: "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj`"
payment_intent_idstring

(Stripe) reference to the payment intent if payment requires confirmation.

Example: "pi_1GYZYWLgUJT2XNPAYQMomeqf"
Response
application/json
{
  "grant_id": "33d576c7-d036-40e7-8141-8a91998a5c79",
  "client_secret": "src_client_secret_QfsM25CJ2uCMon72MiOmUNTj`",
  "payment_intent_id": "pi_1GYZYWLgUJT2XNPAYQMomeqf"
}

Update the subscription

Request

Updates an existing subscription to change the associated product and plan. Updating the subscription may modify the price of the subscription, and if so the balance will be billed immediately at a pro-rated amount. Parameters specific to the vendor may be specified to change the payment method for the subscription. Changing to a plan with a different billing frequency from the existing subscription is not supported for some payment providers (Braintree).

Security
CookieBlaizeSession or JwtQuery or JwtHeaderXBlaizeJwt or JwtHeaderXZephrJwt or JwtBearer or JwtCookie
Headers
cookiestring

The session cookie.

Example: `blaize_session=...` (string)
Bodyapplication/json
product_idstringrequired

Product Id/slug

Example: "premium-access-monthly-recurring"
plan_idstringrequired

Plan Id/slug

Example: "plan-5"
vendor_fieldsobjectrequired

Parameters specific to the payment provider in-use.

Example: {"payment_nonce":"eyJ2ZXmsaW5nQWdyZWmVubW8iOiJvZmYifQ=="}
vendor_fields.​payment_noncestring

(Braintree) Payment method nonce from Braintree drop-in UI. If not specified, the existing payment method on the subscription will be retained.

Example: "eyJ2ZXmsaW5nQWdyZWmVubW8iOiJvZmYifQ=="
navigated_fromstring

Specify where the request was made from. Used as data to pass to change subscription webhooks.

Example: "/some/path"
curl -i -X PATCH \
  https://developer.zuora.com/_mock/zephr-api-reference/zephr-public-api/zephr/subscriptions/:subscriptionId \
  -H 'Content-Type: application/json' \
  -H 'cookie: `blaize_session=...` (string)' \
  -b '`blaize_session=...` (string)' \
  -d '{
    "product_id": "premium-access-monthly-recurring",
    "plan_id": "plan-5",
    "vendor_fields": {
      "payment_nonce": "eyJ2ZXmsaW5nQWdyZWmVubW8iOiJvZmYifQ=="
    },
    "navigated_from": "/some/path"
  }'

Responses

OK

Bodyapplication/json
grant_idstring

New grant of product bundle to user.

Example: "33d576c7-d036-40e7-8141-8a91998a5c79"
Response
application/json
{
  "grant_id": "33d576c7-d036-40e7-8141-8a91998a5c79"
}

Product Sharing

Operations

SDK Feature Decision Engine

Operations

Sessions

Operations

Stripe Payments

Operations

Third-Party Authentication

This section contains the API operations for the OAuth 2.0 Authorization Code Flow.

Operations

User

Operations

V4 Gifts

Create a Gift resource for V4. Gifts can be used to provide access to a particular URL for one session only by appending a gift token ID to the URL as the gift path parameter.

Operations

Web Analytics

Operations

Zephr Features

Operations

Component Library

Operations

Change the Stripe subscription price

Request

Generates a new preview of the price that Stripe will charge the customer if they create a new subscription for the specified plan. Note: This method does not create any entities in Stripe and does not result in any payments being made.

Security
CookieBlaizeSession or JwtQuery or JwtHeaderXBlaizeJwt or JwtHeaderXZephrJwt or JwtBearer or JwtCookie
Path
externalIdstringrequired
Bodyapplication/json
plan_idstring
curl -i -X POST \
  'https://developer.zuora.com/_mock/zephr-api-reference/zephr-public-api/zephr/payment/stripe/subscriptions/{externalId}/change-previews' \
  -H 'Content-Type: application/json' \
  -b blaize_session=YOUR_API_KEY_HERE \
  -d '{
    "plan_id": "string"
  }'

Responses

OK

Bodyapplication/json
totalnumber

The total amount the user will be initially charged for the subscription in the relevant currency's lowest denomination (e.g. pence), i.e. for a monthly subscription, the first month's cost.

Example: 5000
sub_totalnumber

The total amount minus tax for the initial charge in the relevant currency's lowest denomination (e.g. pence).

Example: 4500
Response
application/json
{
  "total": 5000,
  "sub_total": 4500
}

Oauth2 Access Token

Operations

Subscription

Operations