The ServiceAction object

Attributes

idstring
Unique identifier for the ServiceAction.

objectstring, value is "v2.billing.service_action"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

credit_grantnullable object
Details for the credit grant. Provided only if type is “credit_grant”.

credit_grant_per_tenantnullable object
Details for the credit grant per tenant. Provided only if type is “credit_grant_per_tenant”.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for this service action.

service_intervalenum
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service.

typeenum
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

The ServiceAction object

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "4242",
  "lookup_key": "4242",
  "object": "4242",
  "service_interval": "day",
  "service_interval_count": 4242,
  "type": "credit_grant",
  "livemode": true,
  "credit_grant": {
    "amount": {
      "type": "custom_pricing_unit",
      "custom_pricing_unit": {
        "id": "4242",
        "value": "4242"
      },
      "monetary": {
        "currency": "4242",
        "value": "4242"
      }
    },
    "applicability_config": {
      "scope": {
        "billable_items": [
          "4242"
        ],
        "price_type": "metered"
      }
    },
    "expiry_config": {
      "type": "end_of_service_period"
    },
    "name": "4242"
  }
}

createServiceAction v2

Create a ServiceAction object.

Learn more about calling API v2 endpoints.

Parameters

service_intervalenumRequired
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countintegerRequired
The length of the interval for assessing service.

typeenumRequired
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

credit_grantobject
Details for the credit grant. Required if type is “credit_grant”.

credit_grant_per_tenantobject
Details for the credit grant per tenant. Required if type is “credit_grant_per_tenant”.

lookup_keystring
An internal key you can use to search for this service action. Maximum length of 200 characters.

Returns

Response attributes

idstring
Unique identifier for the ServiceAction.

objectstring, value is "v2.billing.service_action"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

credit_grantnullable object
Details for the credit grant. Provided only if type is “credit_grant”.

credit_grant_per_tenantnullable object
Details for the credit grant per tenant. Provided only if type is “credit_grant_per_tenant”.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for this service action.

service_intervalenum
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service.

typeenum
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

Error Codes

400array_must_not_be_empty

Returned by ServiceAction API when the price type is invalid.

400billable_item_not_metered

Returned by ServiceAction API when the billable item is not a metered_item.

400lookup_key_already_used

Returned when another object of the same type already has the given lookup key.

400service_action_type_invalid

Returned by ServiceAction API when the type is invalid.

404billable_item_not_found

Returned when the provided billable_item ID cannot be found.

404custom_pricing_unit_not_found

Returned by CustomPricingUnit API when the custom pricing unit is not found.

404license_fee_not_found

Returned when the provided license_fee ID cannot be found.

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

POST /v2/billing/service_actions

Server-side language

curl -X POST https://api.stripe.com/v2/billing/service_actions \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "service_interval": "day",
    "service_interval_count": 4242,
    "type": "credit_grant"
  }'

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "4242",
  "lookup_key": "4242",
  "object": "4242",
  "service_interval": "day",
  "service_interval_count": 4242,
  "type": "credit_grant",
  "livemode": true,
  "credit_grant": {
    "amount": {
      "type": "custom_pricing_unit",
      "custom_pricing_unit": {
        "id": "4242",
        "value": "4242"
      },
      "monetary": {
        "currency": "4242",
        "value": "4242"
      }
    },
    "applicability_config": {
      "scope": {
        "billable_items": [
          "4242"
        ],
        "price_type": "metered"
      }
    },
    "expiry_config": {
      "type": "end_of_service_period"
    },
    "name": "4242"
  }
}

retrieveServiceAction v2

Retrieve a ServiceAction object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Service Action.

Returns

Response attributes

idstring
Unique identifier for the ServiceAction.

objectstring, value is "v2.billing.service_action"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

credit_grantnullable object
Details for the credit grant. Provided only if type is “credit_grant”.

credit_grant_per_tenantnullable object
Details for the credit grant per tenant. Provided only if type is “credit_grant_per_tenant”.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

lookup_keynullable string
An internal key you can use to search for this service action.

service_intervalenum
The interval for assessing service.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service.

typeenum
The type of the service action.
Possible enum values
credit_grant
The service action is of type credit grant.
credit_grant_per_tenant
The service action is of type credit grant per tenant.

Error Codes

404service_action_not_found

Returned by ServiceAction API when the service action is not found.

GET /v2/billing/service_actions/:id

Server-side language

curl https://api.stripe.com/v2/billing/service_actions/REPLACE ME \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "4242",
  "lookup_key": "4242",
  "object": "4242",
  "service_interval": "day",
  "service_interval_count": 4242,
  "type": "credit_grant",
  "livemode": true,
  "credit_grant": {
    "amount": {
      "type": "custom_pricing_unit",
      "custom_pricing_unit": {
        "id": "4242",
        "value": "4242"
      },
      "monetary": {
        "currency": "4242",
        "value": "4242"
      }
    },
    "applicability_config": {
      "scope": {
        "billable_items": [
          "4242"
        ],
        "price_type": "metered"
      }
    },
    "expiry_config": {
      "type": "end_of_service_period"
    },
    "name": "4242"
  }
}

Rate Cards v2

A RateCard describes usage-based pricing. To bill a customer using a RateCard, create a RateCardSubscription which links it to the corresponding Cadence.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/rate_cards

POST/v2/billing/rate_cards/:id/rates

POST/v2/billing/rate_cards/:id

GET/v2/billing/rate_cards/:id

GET/v2/billing/rate_cards/:id/rates/:id

GET/v2/billing/rate_cards/:id/versions/:id

GET/v2/billing/rate_cards/:id/rates

GET/v2/billing/rate_cards

GET/v2/billing/rate_cards/:id/versions

DELETE/v2/billing/rate_cards/:id/rates/:id

Rate Card Subscriptions v2

A RateCardSubscription links a RateCard to a specific billing Cadence. While the RateCardSubscription is active, Stripe will bill the Payer according to the RateCard’s pricing.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/rate_card_subscriptions

POST/v2/billing/rate_card_subscriptions/:id

GET/v2/billing/rate_card_subscriptions/:id

GET/v2/billing/rate_card_subscriptions

POST/v2/billing/rate_card_subscriptions/:id/cancel

The ServiceAction object

Attributes

idstring

objectstring, value is "v2.billing.service_action"

createdtimestamp

credit_grantnullable object

credit_grant_per_tenantnullable object

livemodeboolean

lookup_keynullable string

service_intervalenum

service_interval_countinteger

typeenum

createServiceAction v2

Parameters

service_intervalenumRequired

service_interval_countintegerRequired

typeenumRequired

credit_grantobject

credit_grant_per_tenantobject

lookup_keystring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.service_action"

createdtimestamp

credit_grantnullable object

credit_grant_per_tenantnullable object

livemodeboolean

lookup_keynullable string

service_intervalenum

service_interval_countinteger

typeenum

retrieveServiceAction v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.service_action"

createdtimestamp

credit_grantnullable object

credit_grant_per_tenantnullable object

livemodeboolean

lookup_keynullable string

service_intervalenum

service_interval_countinteger

typeenum

Rate Cards v2

Rate Card Subscriptions v2