Basejump Logo

Basejump

Billing

If you're just looking for the latest cached billing status, you can use the get_account call.

These billing specific functions will force an upstream billing provider API hit to load fresh data. Also useful for generating billing dashboard links for updating payment methods or changing your subscription plan.

To make implementation simpler, all billing functions are nested under one endpoint. Individual function calls are handled by passing the function name to the billing-functions endpoint

Making billing function calls

Because billing functions share an endpoint, you need to pass through the action to take as well as any arguments for the function.

Making requests

POST
/billing-functions
{
    "action": "get_plans",
    "args": {
        "account_id": "uuid"
    }
}
ACTIONget_plans

Get plans

Returns all the available subscription plans for the given account. The currently selected plan will be indicated.

Optional attributes

  • Name
    account_id
    Type
    uuid
    Description

    UUID for the account you're trying to lookup available plans for. If an account_id is passed, the response will indicate which plan has been selected

Request

ACTION
get_plans
curl -G https://YOUR_SUPABASE/billing-functions \
-X POST \
-H "Authorization: Bearer SUPABASE_AUTH_TOKEN" \
-H "apikey: SUPABASE_ANON_KEY" \
-H "Content-Type: application/json"
-d '{"action": "get_plans", "args": {"account_id": "uuid"}}'

Response

[
    {
        "id": "vendor_plan_id",
        "name": "Plan name",
        "description": "Your plan description",
        "amount": 1000,
        "currency": "usd",
        "interval": "month" | "year" | "one_time",
        "interval_count": 1,
        "trial_period_days": 30,
        "active": false
    },
    ...
]
ACTIONget_billing_status

Billing status

Returns the current billing status for the given account. This includes the currently selected plan, subscription status, etc...

Required attributes

  • Name
    account_id
    Type
    uuid
    Description

    Unique UUID for the account you're trying to lookup

Possible Statuses

  • active - The account has an active subscription
  • trialing - The account is in a trial period
  • past_due - The account has a past due invoice
  • canceled - The account has canceled their subscription
  • unpaid - The account has an unpaid invoice
  • incomplete - The account has not yet finished setting up their subscription
  • incomplete_expired - The account has an expired incomplete invoice

Request

ACTION
get_billing_status
curl -G https://YOUR_SUPABASE/billing-functions \
-X POST \
-H "Authorization: Bearer SUPABASE_AUTH_TOKEN" \
-H "apikey: SUPABASE_ANON_KEY" \
-H "Content-Type: application/json"
-d '{"action": "get_billing_status", "args": {"account_id": "uuid"}}'

Response

{
    "subscription_id": "vendor_subscription_id",
    "subscription_active": true,
    "status": "active",
    "billing_email": "your@email.com",
    "account_role": "owner",
    "is_primary_owner": true,
    "billing_enabled": true,
}
ACTIONget_billing_portal_url

Updating subscription or payment method

Returns a URL for the account to update their subscription or payment method. This URL will redirect the user to your billing provider's hosted page (Stripe, for example) where they can update their subscription or payment method.

Required attributes

  • Name
    account_id
    Type
    uuid
    Description

    UUID for the account you're trying to lookup available plans for. If an account_id is passed, the response will indicate which plan has been selected

  • Name
    return_url
    Type
    string
    Description

    Where the user should be returned to once done. Must have an origin matching what's defined in the billing-functions endpoint.

Request

ACTION
get_billing_portal_url
curl -G https://YOUR_SUPABASE/billing-functions \
-X POST \
-H "Authorization: Bearer SUPABASE_AUTH_TOKEN" \
-H "apikey: SUPABASE_ANON_KEY" \
-H "Content-Type: application/json"
-d '{"action": "get_billing_portal_url", "args": {"account_id": "uuid", "return_url": "string"}}'

Response

{
    "url": "https://link-to-vendor-page",
    "billing_enabled": true
}
ACTIONget_new_subscription_url

Start new subscription

Returns a URL for the account to start a new subscription. This URL will redirect the user to your billing provider's hosted page (Stripe, for example) where they can start a new subscription.

Required attributes

  • Name
    account_id
    Type
    uuid
    Description

    UUID for the account you're trying to lookup available plans for. If an account_id is passed, the response will indicate which plan has been selected

  • Name
    success_url
    Type
    string
    Description

    Where the user should be returned if successful. The url passed in must have an origin matching what's been setup in the billing-functions endpoint.

  • Name
    cancel_url
    Type
    string
    Description

    Where the user should be returned if they cancel before completing. The url passed in must have an origin matching what's been setup in the billing-functions endpoint.

Optional attributes

  • Name
    plan_id
    Type
    string
    Description

    The billing provider's plan id you want to subscribe the account to. This can either be pulled manually from your providers dashboard or by calling the get_plans action. If not sent, the defined default plan will be used.

Request

ACTION
get_new_subscription_url
curl -G https://YOUR_SUPABASE/billing-functions \
-X POST \
-H "Authorization: Bearer SUPABASE_AUTH_TOKEN" \
-H "apikey: SUPABASE_ANON_KEY" \
-H "Content-Type: application/json"
-d '{"action": "get_new_subscription_url", "args": {"account_id": "uuid", "plan_id": "string", "success_url": "string", "cancel_url": "string"}}'

Response

{
    "url": "https://link-to-vendor-page",
    "billing_enabled": true
}
POST/billing-webhooks

Webhooks

This is a separate Supabase edge function that consumes webhooks from your billing provider to keep your Supabase database up to date. This is separate from the billing-functions endpoint.

Follow the provider setup instructions to learn more about how to configure webhooks for your billing provider.

Request

POST
/billing-webhooks
curl -G https://YOUR_SUPABASE/billing-webhooks \
-X POST \
-H "Content-Type: application/json"
-d '{ ...provider-payload }'

Response

{
    "status": "ok"
}