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

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingPlans

Authorizations

bearerAuth

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.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/billingPlans

HTTPcURLJavaScriptPython

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-06-15",
      "updateTime": "2026-06-15"
    }
  ],
  "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

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingPlans/create

Authorizations

bearerAuth

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

/billingPlans/create

HTTPcURLJavaScriptPython

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-06-15",
  "updateTime": "2026-06-15"
}

Get Billing Plan

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

Get billing plan

get

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingPlans/{planId}

Authorizations

bearerAuth

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.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/billingPlans/{planId}

HTTPcURLJavaScriptPython

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-06-15",
  "updateTime": "2026-06-15"
}

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

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingPlans/{planId}

Authorizations

bearerAuth

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

put

/billingPlans/{planId}

HTTPcURLJavaScriptPython

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

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingPlans/{planId}/activate

Authorizations

bearerAuth

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

put

/billingPlans/{planId}/activate

HTTPcURLJavaScriptPython

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

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingPlans/{planId}/deactivate

Authorizations

bearerAuth

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

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

put

/billingPlans/{planId}/deactivate

HTTPcURLJavaScriptPython

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