Change Tier

Apply a product group membership to a subscription item to perform an upgrade or downgrade.

POST /product-group-memberships/{id}/apply

cURL

cURL

curl -X POST \
 /product-group-memberships/{id}/apply \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --data '{"subscriptionItem": "item-uuid", "selectedPricePlan": "plan-uuid", "quantity": 1}'

200

{
  "subscriptionItem": {
    "id": "01F9ZQZJZJQZJZJZJZJZJZJZJZ",
    "parent": "<unknown>",
    "plan": {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "family": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
      },
      "code": "basic-m2023",
      "originProduct": {
        "measurement": {
          "unit": {
            "id": {},
            "name": "Stück"
          },
          "code": "users",
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "description": "The number of users.",
          "aggregationType": "sum",
          "fairBilling": true,
          "type": "recurring"
        },
        "taxGroup": {},
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "name": "Basic",
        "description": "For small teams.",
        "internalName": "Basic (Weekly)",
        "costCentre": {},
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "allowCheckout": true,
      "status": "draft",
      "createdAt": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "description": "<string>"
    },
    "measurementValues": [
      {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "measurement": {
          "unit": {
            "id": {},
            "name": "Stück"
          },
          "code": "users",
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "description": "The number of users.",
          "aggregationType": "sum",
          "fairBilling": true,
          "type": "recurring"
        },
        "quantity": 1,
        "measuredAt": "2021-01-01T00:00:00+00:00"
      }
    ],
    "billing": {
      "lastBilledAt": "2023-11-07T05:31:56Z",
      "lastBilledTo": "2023-11-07T05:31:56Z",
      "lastBilledFrom": "2023-11-07T05:31:56Z",
      "nextBillingAt": "2023-11-07T05:31:56Z",
      "billingInterval": "1M"
    },
    "name": "Fitness M",
    "description": "Everything included",
    "furtherInformation": "Additional agreements: The contract includes a free drink flatrate.",
    "pricePlan": {
      "type": "flat_fee",
      "price": {
        "amount": 123,
        "createdAt": "2021-01-01T00:00:00+00:00",
        "updatedAt": "2021-01-01T00:00:00+00:00",
        "tenantId": "<string>"
      },
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "internalName": "Exclusive pricing for partners.",
      "status": "active",
      "applyTrial": true,
      "payInAdvance": true,
      "proRata": true,
      "freeUnits": 1,
      "billingInterval": "1M",
      "showPricePerInterval": "1M",
      "custom": true,
      "charge": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "productSetOption": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "inUse": true
    },
    "status": "active",
    "product": {
      "measurement": {
        "unit": {
          "id": {},
          "name": "Stück"
        },
        "code": "users",
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "description": "The number of users.",
        "aggregationType": "sum",
        "fairBilling": true,
        "type": "recurring"
      },
      "taxGroup": {},
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "name": "Basic",
      "description": "For small teams.",
      "internalName": "Basic (Weekly)",
      "costCentre": {},
      "customFields": {
        "field1": "value1",
        "field2": "value2"
      }
    },
    "appliedDiscounts": [
      {
        "id": "<string>",
        "coupon": {
          "code": "10OFF",
          "name": "10% off",
          "type": "percentage",
          "frequency": "limited",
          "id": "<string>",
          "percentage": 10,
          "fixedAmount": {},
          "frequencyInterval": 3,
          "maxRedemptionsPerCustomer": "null",
          "maxRedemptions": "null",
          "expiresAt": "null",
          "limitedToPlans": [
            {
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "family": {
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
              },
              "code": "basic-m2023",
              "originProduct": {
                "measurement": {
                  "unit": {
                    "id": {},
                    "name": "Stück"
                  },
                  "code": "users",
                  "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                  "description": "The number of users.",
                  "aggregationType": "sum",
                  "fairBilling": true,
                  "type": "recurring"
                },
                "taxGroup": {},
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "name": "Basic",
                "description": "For small teams.",
                "internalName": "Basic (Weekly)",
                "costCentre": {},
                "customFields": {
                  "field1": "value1",
                  "field2": "value2"
                }
              },
              "allowCheckout": true,
              "status": "draft",
              "createdAt": "2023-11-07T05:31:56Z",
              "name": "<string>",
              "description": "<string>"
            }
          ],
          "excludedFromPlans": [
            {
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "family": {
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
              },
              "code": "basic-m2023",
              "originProduct": {
                "measurement": {
                  "unit": {
                    "id": {},
                    "name": "Stück"
                  },
                  "code": "users",
                  "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                  "description": "The number of users.",
                  "aggregationType": "sum",
                  "fairBilling": true,
                  "type": "recurring"
                },
                "taxGroup": {},
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "name": "Basic",
                "description": "For small teams.",
                "internalName": "Basic (Weekly)",
                "costCentre": {},
                "customFields": {
                  "field1": "value1",
                  "field2": "value2"
                }
              },
              "allowCheckout": true,
              "status": "draft",
              "createdAt": "2023-11-07T05:31:56Z",
              "name": "<string>",
              "description": "<string>"
            }
          ],
          "limitedToProducts": [
            {
              "measurement": {
                "unit": {
                  "id": {},
                  "name": "Stück"
                },
                "code": "users",
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "description": "The number of users.",
                "aggregationType": "sum",
                "fairBilling": true,
                "type": "recurring"
              },
              "taxGroup": {},
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "name": "Basic",
              "description": "For small teams.",
              "internalName": "Basic (Weekly)",
              "costCentre": {},
              "customFields": {
                "field1": "value1",
                "field2": "value2"
              }
            }
          ],
          "excludedFromProducts": [
            {
              "measurement": {
                "unit": {
                  "id": {},
                  "name": "Stück"
                },
                "code": "users",
                "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
                "description": "The number of users.",
                "aggregationType": "sum",
                "fairBilling": true,
                "type": "recurring"
              },
              "taxGroup": {},
              "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
              "name": "Basic",
              "description": "For small teams.",
              "internalName": "Basic (Weekly)",
              "costCentre": {},
              "customFields": {
                "field1": "value1",
                "field2": "value2"
              }
            }
          ],
          "isEnabled": true,
          "reedemptions": true
        },
        "status": "active",
        "discount": {
          "name": "10% off",
          "type": "percentage",
          "frequency": "limited",
          "percentage": 10,
          "fixedAmount": {},
          "frequencyInterval": 3
        },
        "appliedIntervals": 1
      }
    ],
    "periods": [
      {
        "id": "<string>",
        "contractPeriodCount": 123,
        "contractPeriod": {},
        "cancellationPeriod": {},
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "activatedAt": "2021-01-01T00:00:00+00:00",
    "type": "addon",
    "currentMeasurementValue": {
      "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
      "measurement": {
        "unit": {
          "id": {},
          "name": "Stück"
        },
        "code": "users",
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "description": "The number of users.",
        "aggregationType": "sum",
        "fairBilling": true,
        "type": "recurring"
      },
      "quantity": 1,
      "measuredAt": "2021-01-01T00:00:00+00:00"
    },
    "inheritedPeriod": true
  },
  "creditNote": {
    "id": "<string>",
    "number": "<string>",
    "amount": 123
  }
}

Change the tier (membership) of a subscription item to perform an upgrade or downgrade.

​

Flow

1. Get available options via GET /subscription-items/{id}/change-options
2. Select a tier from the options
3. Execute the tier change using this endpoint

​

Request Parameters

Parameter	Required	Description
subscriptionItem	Yes	UUID of the subscription item to change
selectedPricePlan	No	UUID of the price plan. Only required if the tier has multiple price plans configured. In most cases, each tier has a single price plan and this field can be omitted.
quantity	No	New quantity. Only applied if the tier allows quantity changes.
sendInvoiceEmail	No	Send credit note via email (default: true)

​

Response

Returns the updated subscription item and any created credit note.

Implementation Guide

Complete guide for implementing self-service upgrades

Autorisierungen

Authorization · string · header · erforderlich

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Pfadparameter

id · string · erforderlich

ProductGroupMembership identifier

Body

application/json

subscriptionItem · string · erforderlich

UUID of the subscription item to change

selectedPricePlan · string

UUID of the selected price plan (optional if only one available)

quantity · integer

New quantity (optional)

Beispiel:

1

sendInvoiceEmail · boolean · Standard: true

Whether to send credit note via email

Antwort

200

application/json

Membership applied successfully

Result of applying a product group membership

subscriptionItem · object

Show child attributes

creditNote · object

Show child attributes