import React from "react"; import CodeSnippet from "$app/components/ui/CodeSnippet"; import { ApiEndpoint } from "../ApiEndpoint"; import { ApiParameter, ApiParameters } from "../ApiParameters"; import { ApiResponseFields, renderFields } from "../ApiResponseFields"; import { RESOURCE_SUBSCRIPTION_FIELDS } from "../responseFieldDefinitions"; const ResourceSubscriptionsDescription = () => ( <>
Subscribe to a resource. Currently there are 8 supported resource names - "sale", "refund", "dispute", "dispute_won", "cancellation", "subscription_updated", "subscription_ended", and "subscription_restarted".
sale - When subscribed to this resource, you will be notified of the user's sales with an HTTP POST to your post_url. The format of the POST is described on the Gumroad Ping page.
refund - When subscribed to this resource, you will be notified of refunds to the user's sales with an HTTP POST to your post_url. The format of the POST is same as described on the{" "} Gumroad Ping page.
dispute - When subscribed to this resource, you will be notified of the disputes raised against user's sales with an HTTP POST to your post_url. The format of the POST is described on the{" "} Gumroad Ping page.
dispute_won - When subscribed to this resource, you will be notified of the sale disputes won by the user with an HTTP POST to your post_url. The format of the POST is described on the{" "} Gumroad Ping page.
cancellation - When subscribed to this resource, you will be notified of cancellations of the user's subscribers with an HTTP POST to your post_url.
subscription_updated - When subscribed to this resource, you will be notified when subscriptions to the user's products have been upgraded or downgraded with an HTTP POST to your post_url. A subscription is "upgraded" when the subscriber switches to an equally or more expensive tier and/or subscription duration. It is "downgraded" when the subscriber switches to a less expensive tier and/or subscription duration. In the case of a downgrade, this change will take effect at the end of the current billing period. (Note: This currently applies only to tiered membership products, not to all subscription products.)
subscription_ended - When subscribed to this resource, you will be notified when subscriptions to the user's products have ended with an HTTP POST to your post_url. These events include termination of a subscription due to: failed payment(s); cancellation; or a subscription of fixed duration ending. Notifications are sent at the time the subscription has officially ended, not, for example, at the time cancellation is requested.
subscription_restarted - When subscribed to this resource, you will be notified when subscriptions to the user's products have been restarted with an HTTP POST to your post_url. A subscription is "restarted" when the subscriber restarts their subscription after previously terminating it.
In each POST request, Gumroad sends these parameters:
subscription_id: id of the subscription
product_id: id of the product
product_name: name of the product
user_id: user id of the subscriber
user_email: email address of the subscriber
purchase_ids: array of charge ids belonging to this subscription
created_at: timestamp when subscription was created
charge_occurrence_count: number of charges made for this subscription
recurrence: subscription duration - monthly/quarterly/biannually/yearly/every_two_years
free_trial_ends_at: timestamp when free trial ends, if free trial is enabled for the membership
custom_fields: custom fields from the original purchase
license_key: license key from the original purchase
For "cancellation" resource:
cancelled: true if subscription has been cancelled, otherwise false
cancelled_at: timestamp at which subscription will be cancelled
cancelled_by_admin: true if subscription was been cancelled by admin, otherwise not present
cancelled_by_buyer: true if subscription was been cancelled by buyer, otherwise not present
cancelled_by_seller: true if subscription was been cancelled by seller, otherwise not present
cancelled_due_to_payment_failures: true if subscription was been cancelled automatically
because of payment failure, otherwise not present
For "subscription_updated" resource:
type: "upgrade" or "downgrade"
effective_as_of: timestamp at which the change went or will go into effect
old_plan: tier, subscription duration, price, and quantity of the subscription before the
change
new_plan: tier, subscription duration, price, and quantity of the subscription after the change
Example
{`{
...
type: "upgrade",
effective_as_of: "2021-02-23T16:31:44Z",
old_plan: {
tier: { id: "G_-mnBf9b1j9A7a4ub4nFQ==", name: "Basic tier" },
recurrence: "monthly",
price_cents: "1000",
quantity: 1
},
new_plan: {
tier: { id: "G_-mnBf9b1j9A7a4ub4nFQ==", name: "Basic tier" },
recurrence: "yearly",
price_cents: "12000",
quantity: 2
}
}`}
For "subscription_ended" resource:
ended_at: timestamp at which the subscription ended
ended_reason: the reason for the subscription ending ("cancelled", "failed_payment", or
"fixed_subscription_period_ended")
For "subscription_restarted" resource:
restarted_at: timestamp at which the subscription was restarted