Billing

Discord supports a variety of payment providers to enable billing for first-party and third-party monetization.

Payment Source Object

Payment Source Structure

¹ Not available in payment objects.

Example Payment Source

{
  "id": "1422548914485198869",
  "type": 1,
  "invalid": false,
  "flags": 0,
  "deleted_at": null,
  "brand": "visa",
  "last_4": "4242",
  "expires_month": 9,
  "expires_year": 2077,
  "billing_address": {
    "name": "John Doe",
    "line_1": "123 Main Street",
    "line_2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "country": "US",
  "payment_gateway": 1,
  "payment_gateway_source_id": "pm_DwiVlGlYwe1qxLzy4QWChQeo",
  "default": false
}

Billing Address Structure

Payment Source Type

Payment Gateway

¹ Payment gateway is internal and cannot be used directly.

Payment Source Flags

Gateway Checkout Context Object

Gateway Checkout Context Structure

User Trial Offer Object

User Trial Offer Structure

¹ Trial offers only gain an expiration date when they are acknowledged.

Example User Trial Offer

{
  "id": "1433666591022645361",
  "user_id": "852892297661906993",
  "trial_id": "1073698058383917056",
  "subscription_trial": {
    "id": "1073698058383917056",
    "interval": 3,
    "interval_count": 14,
    "sku_id": "521847234246082599"
  },
  "expires_at": "2025-11-04T07:26:18.125782+00:00"
}

User Discount Offer Object

User Discount Offer Structure

¹ These fields are only present for applied offers.

² Discount offers only gain an expiration date when they are acknowledged.

Discount Structure

Discount Status

The values of this enum are currently unknown. Help us by figuring them out and submitting a pull request!

Example User Discount Offer

{
  "id": "1433666591022645360",
  "user_id": "852892297661906993",
  "discount_id": "1204865493622587392",
  "applied_at": null,
  "expires_at": "2025-11-04T07:26:18.125782+00:00",
  "discount": {
    "id": "1204865493622587392",
    "amount": 30,
    "starts_at": null,
    "ends_at": null,
    "status": 2,
    "created_at": "2024-02-08T16:44:28.903181+00:00",
    "sku_ids": null,
    "sku_group_ids": null,
    "plan_ids": ["511651880837840896"],
    "user_usage_limit_interval": 3,
    "user_usage_limit_interval_count": 1,
    "user_usage_limit": 1
  }
}

Endpoints

Returns the user's country code based on requesting IP address.

Response Body

Returns the user's country and subdivision code based on requesting IP address.

Response Body

Returns a list of payment source objects. Note that the billing_address fields within these objects will be partial for security reasons, containing only name and country.

Returns a payment source object for a given payment source ID.

Creates a payment source. Returns a payment source object on success. Fires a User Payment Sources Update Gateway event.

JSON Params

Modifies a payment source. Returns an updated payment source object on success. Fires a User Payment Sources Update Gateway event.

JSON Params

Deletes a payment source. Returns a 204 empty response on success. Fires a User Payment Sources Update Gateway event.

Validates a billing address.

Response Body

Creates a Stripe SetupIntent and returns the client secret. See the Stripe documentation for more information.

JSON Params

Response Body

Creates a PayPal billing agreement and returns its token. See the PayPal documentation for more information. This token is used to redirect the user to PayPal to approve the billing agreement through a URL: https://www.paypal.com/agreements/approve?nolegacy=1&ba_token={token}

JSON Params

¹ These URLs are typically set to the Create Billing Popup Bridge Redirect endpoint (with a response_type of return and cancel, respectively), which redirects the user back to the Discord client for handling.

Response Body

Returns available payment methods for the ADYEN payment gateway. This endpoint is a proxy for getting available payment methods for transactions using the Adyen API. See the Adyen documentation for more information.

Creates a billing popup bridge to handle third-party payment flows.

Response Body

Redirects the user back to the Discord client after completing a third-party payment flow. The client uses Create Billing Popup Bridge Callback to complete the flow.

Completes a third-party payment flow after being redirected back from the payment provider. Returns a 204 empty response on success. Fires a Billing Popup Bridge Callback Gateway event.

JSON Params

Returns localized pricing promo information for the user based on their country.

Response Body

Localized Pricing Promo Structure

Localized Price Structure

Returns the current trial and discount offers for the user, if any.

JSON Params

Response Body

Acknowledges that the user has seen a trial or discount offer.

JSON Params

Response Body

Creates a discount offer as a retention attempt for a user in a non-renewing state, if allowed.

Response Body

Returns the current retention discount offer for a user in a non-renewing state, if any.

Response Body

Returns a user trial offer object for the user, if any.

Acknowledges that the user has seen a trial offer. Returns the acknowledged user trial offer object on success.

Redeems a discount offer for the user. Returns a list of applied user discount offer objects on success.

JSON Params

Returns whether the client should prompt the user to continue their premium purchase.

Response Body

Returns a list of up to 3 partial user objects representing friends with a premium subscription, used to entice the user to subscribe.