Ctrlk
RegisterLogin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Billing Plans

Billing Plans define the pricing, billing cycles, and payment terms that subscribers are enrolled into. A plan belongs to a Product and is the template from which Subscriptions are created.

Plans can be activated or deactivated to control availability without deletion.

How It Works

1

Create a product

A billing plan must be associated with a product. See Products for how to create one.

2

Create a billing plan

Call POST /billingPlans/create with the product ID, pricing structure, and billing cycle configuration.

3

Activate the plan

New plans may require activation before subscribers can enroll. Call PUT /billingPlans/{planId}/activate.

4

Create subscriptions

With an active plan, call POST /subscriptions to enrol subscribers. See Subscriptions.

List Billing Plans

Returns a paginated list of billing plans. Filter by product ID or specific plan IDs.

List billing plans

get
/billingPlans
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

productIdstring · min: 6 · max: 50Optional

Filters the response by a Product ID.

idsstring · min: 6 · max: 270Optional

Filters the response by list of plan IDs.

pageSizenumber · min: 1 · max: 20Optional

The number of items to return in the response.

pagenumber · min: 1 · max: 100000Optional

A non-zero integer which is the start index of the entire list of items to return in the response.

totalRequiredbooleanOptional

Indicates whether to show the total count in the response.

Responses
200

Successful

application/json
totalItemsnumberOptional

The total number of items.

totalPagesnumberOptional

The total number of pages.

get/billingPlans
GET /oidc/paypal-ecom/billingPlans?paymentProviderContract=text HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "plans": [
    {
      "id": "text",
      "name": "text",
      "billingCycles": [
        {
          "pricingScheme": {
            "version": 1,
            "fixedPrice": {
              "currencyCode": "EUR",
              "value": 100
            },
            "pricingModel": "VOLUME",
            "tiers": [
              {
                "startingQuantity": "text",
                "endingQuantity": "text",
                "amount": {
                  "currencyCode": "EUR",
                  "value": 100
                }
              }
            ]
          },
          "frequency": {
            "intervalUnit": "DAY",
            "intervalCount": 1
          },
          "tenureType": "REGULAR",
          "sequence": 1,
          "totalCycles": 1
        }
      ],
      "paymentPreferences": {
        "autoBillOutstanding": true,
        "setupFee": {
          "currencyCode": "EUR",
          "value": 100
        },
        "setupFeeFailureAction": "CONTINUE",
        "paymentFailureThreshold": 1
      },
      "status": "ACTIVE",
      "description": "text",
      "taxes": {
        "percentage": "text",
        "inclusive": true
      },
      "quantitySupported": true,
      "createTime": "2026-01-01",
      "updateTime": "2026-01-01"
    }
  ],
  "totalItems": 1,
  "totalPages": 1
}

Create Billing Plan

Creates a new billing plan under an existing product. Specify billing cycles, pricing scheme (fixed price or tiered), and payment preferences.

Use x-vfi-api-idempotencyKey to prevent duplicate plan creation on retries.

Create billing plan

post
/billingPlans/create
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Header parameters
x-vfi-api-idempotencyKeystringOptional

A value you specify that uniquely identifies the transaction. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the transaction.

Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

productIdstringRequired

PayPal catalog product id

namestring · max: 127Required

The plan name

statusstring · enumOptional

The initial state of the plan

Possible values:
descriptionstring · max: 127Optional

The detailed description of the plan.

quantitySupportedbooleanOptional

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

Responses
201

Created

application/json
idstring · min: 6 · max: 50Required

The unique PayPal-generated ID for the plan.

productIdstringRequired

PayPal catalog product id

namestring · max: 127Required

The plan name

statusstring · enumRequired

The initial state of the plan

Possible values:
descriptionstring · max: 127Optional

The detailed description of the plan.

quantitySupportedbooleanOptional

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

createTimestring · dateRequired

The date and time when the billing plan was created.

updateTimestring · dateOptional

The date and time when the billing plan was updated.

post/billingPlans/create
POST /oidc/paypal-ecom/billingPlans/create HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 670

{
  "paymentProviderContract": "text",
  "productId": "text",
  "name": "text",
  "status": "ACTIVE",
  "description": "text",
  "billingCycles": [
    {
      "pricingScheme": {
        "version": 1,
        "fixedPrice": {
          "currencyCode": "EUR",
          "value": 100
        },
        "pricingModel": "VOLUME",
        "tiers": [
          {
            "startingQuantity": "text",
            "endingQuantity": "text",
            "amount": {
              "currencyCode": "EUR",
              "value": 100
            }
          }
        ]
      },
      "frequency": {
        "intervalUnit": "DAY",
        "intervalCount": 1
      },
      "tenureType": "REGULAR",
      "sequence": 1,
      "totalCycles": 1
    }
  ],
  "paymentPreferences": {
    "autoBillOutstanding": true,
    "setupFee": {
      "currencyCode": "EUR",
      "value": 100
    },
    "setupFeeFailureAction": "CONTINUE",
    "paymentFailureThreshold": 1
  },
  "taxes": {
    "percentage": "text",
    "inclusive": true
  },
  "quantitySupported": true
}
{
  "id": "text",
  "productId": "text",
  "name": "text",
  "status": "ACTIVE",
  "description": "text",
  "billingCycles": [
    {
      "pricingScheme": {
        "version": 1,
        "fixedPrice": {
          "currencyCode": "EUR",
          "value": 100
        },
        "pricingModel": "VOLUME",
        "tiers": [
          {
            "startingQuantity": "text",
            "endingQuantity": "text",
            "amount": {
              "currencyCode": "EUR",
              "value": 100
            }
          }
        ]
      },
      "frequency": {
        "intervalUnit": "DAY",
        "intervalCount": 1
      },
      "tenureType": "REGULAR",
      "sequence": 1,
      "totalCycles": 1
    }
  ],
  "paymentPreferences": {
    "autoBillOutstanding": true,
    "setupFee": {
      "currencyCode": "EUR",
      "value": 100
    },
    "setupFeeFailureAction": "CONTINUE",
    "paymentFailureThreshold": 1
  },
  "taxes": {
    "percentage": "text",
    "inclusive": true
  },
  "quantitySupported": true,
  "createTime": "2026-01-01",
  "updateTime": "2026-01-01"
}

Get Billing Plan

Retrieves the full details of a billing plan by its ID.

Get billing plan

get
/billingPlans/{planId}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
planIdstringRequired

PayPal billing plan Id

Query parameters
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses
200

Successful

application/json
idstring · min: 6 · max: 50Optional

Filters the response by a Product ID.

productIdstringRequired

PayPal catalog product id

namestring · max: 127Required

The plan name

statusstring · enumOptional

The initial state of the plan

Possible values:
descriptionstring · max: 127Optional

The detailed description of the plan.

quantitySupportedbooleanOptional

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

createTimestring · dateRequired

The date and time when the billing plan was created.

updateTimestring · dateOptional

The date and time when the billing plan was updated.

get/billingPlans/{planId}
GET /oidc/paypal-ecom/billingPlans/{planId}?paymentProviderContract=text HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "productId": "text",
  "name": "text",
  "billingCycles": [
    {
      "pricingScheme": {
        "version": 1,
        "fixedPrice": {
          "currencyCode": "EUR",
          "value": 100
        },
        "pricingModel": "VOLUME",
        "tiers": [
          {
            "startingQuantity": "text",
            "endingQuantity": "text",
            "amount": {
              "currencyCode": "EUR",
              "value": 100
            }
          }
        ]
      },
      "frequency": {
        "intervalUnit": "DAY",
        "intervalCount": 1
      },
      "tenureType": "REGULAR",
      "sequence": 1,
      "totalCycles": 1
    }
  ],
  "paymentPreferences": {
    "autoBillOutstanding": true,
    "setupFee": {
      "currencyCode": "EUR",
      "value": 100
    },
    "setupFeeFailureAction": "CONTINUE",
    "paymentFailureThreshold": 1
  },
  "status": "ACTIVE",
  "description": "text",
  "taxes": {
    "percentage": "text",
    "inclusive": true
  },
  "quantitySupported": true,
  "createTime": "2026-01-01",
  "updateTime": "2026-01-01"
}

Update Billing Plan

Updates fields on an existing billing plan, including pricing scheme, billing cycles, taxes, and payment preferences. Returns 204 No Content on success.

Update billing plans

put
/billingPlans/{planId}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
planIdstringRequired

PayPal billing plan Id

Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

descriptionstring · max: 127Optional

The detailed description of the plan.

Responses
204

No Content

put/billingPlans/{planId}
PUT /oidc/paypal-ecom/billingPlans/{planId} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 244

{
  "paymentProviderContract": "text",
  "description": "text",
  "paymentPreferences": {
    "autoBillOutstanding": true,
    "setupFee": {
      "currencyCode": "EUR",
      "value": 100
    },
    "setupFeeFailureAction": "CONTINUE",
    "paymentFailureThreshold": 1
  },
  "taxes": {
    "percentage": "text"
  }
}
No content

Activate Billing Plan

Activates a billing plan, making it available for new subscriptions.

Activate billing plans

put
/billingPlans/{planId}/activate
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
planIdstringRequired

PayPal billing plan Id

Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses
204

No Content

put/billingPlans/{planId}/activate
PUT /oidc/paypal-ecom/billingPlans/{planId}/activate HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 34

{
  "paymentProviderContract": "text"
}
No content

Deactivate Billing Plan

Deactivates a billing plan. Deactivated plans cannot be used for new subscriptions, but existing active subscriptions are not affected.

Deactivation is reversible — you can reactivate a deactivated plan using PUT /billingPlans/{planId}/activate.

Deactivate billing plans

put
/billingPlans/{planId}/deactivate
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
planIdstringRequired

PayPal billing plan Id

Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses
204

No Content

put/billingPlans/{planId}/deactivate
PUT /oidc/paypal-ecom/billingPlans/{planId}/deactivate HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 34

{
  "paymentProviderContract": "text"
}
No content
PreviousProducts
NextSubscriptions

Last updated

Was this helpful?