creem is a Go client for the Creem API and a verifier for its webhooks:
the server side of selling through Creem as merchant of record - one-time
products, custom amounts, subscriptions, seats, upgrades, refunds and signed
events. Standard library only.
Ukrainian version: README.UK.md.
Creem hosts the checkout, charges and handles tax; your server creates sessions and acts on events. The traps are the same as with any provider, plus two of Creem's own:
- The amount must come from the server. Checkouts are created here, and a custom price for a credit pack is validated before it is sent.
- The webhook signature has no timestamp. A captured delivery would
verify forever. The package checks the event's
created_at- which is in the signed body - and refuses an event older than two days, and the event id must still be stored and checked. - Shapes vary. Timestamps arrive as ISO strings on some entities and as
milliseconds on others; references arrive as ids or as expanded objects.
TimeandExpandableread both, so a handler does not break on the day a field changes form. - A failed POST may have succeeded. A refund or cancellation is not retried after a 5xx; only what cannot have run is.
- A lost webhook is lost money. Creem stops retrying after a day;
ListTransactionslets a periodic job find what never arrived.
- Checkout sessions with
request_id, metadata, a prefilled customer, discount codes and custom prices for one-time products. - Subscriptions: get, cancel (at once or at the period end), pause, resume, upgrade to another product, change the number of seats.
- Full refunds; customers by id or email; billing portal links; transactions, one by one or paged for reconciliation.
- Webhooks: HMAC-SHA256 signature check with secret rotation and an age check; typed checkouts, subscriptions, refunds and disputes.
- Typed
*APIError; the host follows the key (test or live); no redirects followed, ids checked against an allowlist, keys never printed. - Zero dependencies.
go get github.com/goloop/creemc := creem.New(os.Getenv("CREEM_API_KEY")) // a test key talks to the test host
co, err := c.CreateCheckout(ctx, &creem.CheckoutRequest{
ProductID: "prod_credits",
RequestID: purchaseID,
CustomPrice: 1000, // cents, one-time products only
Customer: &creem.CheckoutCustomer{Email: email},
SuccessURL: "https://app.example.com/billing?paid=1",
})
// redirect to co.CheckoutURL| Model | Example | How |
|---|---|---|
| One-time, fixed price | a licence, a fixed pack | a one-time product |
| One-time, amount from the server | credit packs, custom orders | CustomPrice on one one-time product |
| Subscription | $15 a month, $60 a year | a subscription product per term (monthly, 3 or 6 months, yearly) |
| Seats | $8 per member | Units at checkout, UpdateSubscriptionItems later |
| Plan changes | Personal to Team, monthly to yearly | UpgradeSubscription with a proration behaviour |
| Cancel, pause, change of mind | cancel at the period end | CancelSubscription, ResumeSubscription, PauseSubscription |
| Discounts | a launch code | DiscountCode at checkout |
| Refunds and chargebacks | 14-day withdrawal | RefundTransaction (full only), refund.created, dispute.created |
Not available through Creem: a recurring amount decided on the server
(CustomPrice is for one-time products only), partial refunds, invoices
with payment terms, and terms longer than a year among the standard billing
periods. Credits and allowances live in
goloop/ledger. The reference shows every
model in code: Selling models.
wh := creem.NewWebhook(os.Getenv("CREEM_WEBHOOK_SECRET"))
http.HandleFunc("POST /webhooks/creem", func(w http.ResponseWriter, r *http.Request) {
ev, err := wh.ParseRequest(r) // also refuses an event older than DefaultMaxAge
if err != nil {
http.Error(w, "bad signature", http.StatusBadRequest)
return
}
ctx := r.Context()
// // The event table is a shortcut, not the guard: apply is idempotent on
// its own (keyed writes), and an event is marked done only after it was
// applied, so a failure here is retried by Creem and never lost.
done, err := events.Done(ctx, ev.ID) // your table
if err != nil {
http.Error(w, "retry", http.StatusInternalServerError)
return
}
if done {
w.WriteHeader(http.StatusOK)
return
}
if err := apply(ctx, ev); err != nil {
http.Error(w, "retry", http.StatusInternalServerError) // Creem sends it again
return
}
if err := events.MarkDone(ctx, ev.ID); err != nil {
http.Error(w, "retry", http.StatusInternalServerError)
return
}
w.WriteHeader(http.StatusOK)
})
func apply(ctx context.Context, ev *creem.Event) error {
switch ev.Type {
case creem.EventCheckoutCompleted:
co, err := ev.Checkout()
if err != nil {
return err
}
if co.Order == nil {
return fmt.Errorf("checkout %s completed without an order", co.ID)
}
// // Compare the amount and currency with the purchase, then credit, keyed by the transaction id.
return purchases.Paid(ctx, co.RequestID, co.Order.Transaction, co.Order.AmountPaid, co.Order.Currency)
case creem.EventSubscriptionPaid, creem.EventSubscriptionCanceled, creem.EventSubscriptionExpired:
sub, err := ev.Subscription()
if err != nil {
return err
}
return entitlements.Sync(ctx, sub, ev.CreatedAt.Time) // ignores an event older than the state
case creem.EventRefundCreated:
ref, err := ev.Refund()
if err != nil {
return err
}
return purchases.Refunded(ctx, ref.Transaction.ID, ref.ID, ref.RefundAmount) // // may be partial (refunded from the dashboard): take back in proportion, keyed by ref.ID
case creem.EventDisputeCreated:
d, err := ev.Dispute()
if err != nil {
return err
}
return purchases.Refunded(ctx, d.Transaction.ID, d.ID, d.Amount)
}
return nil
}| Call | Endpoint |
|---|---|
CreateCheckout, GetCheckout |
/v1/checkouts |
GetSubscription, CancelSubscription, PauseSubscription, ResumeSubscription |
/v1/subscriptions[/{id}/cancel,/pause,/resume] |
UpgradeSubscription, UpdateSubscriptionItems |
/v1/subscriptions/{id}[/upgrade] |
RefundTransaction |
/v1/refunds |
GetCustomer, CustomerByEmail, CustomerPortalLink |
/v1/customers[/billing] |
GetTransaction, ListTransactions |
/v1/transactions[/search] |
NewWebhook, Webhook.ParseRequest, Sign |
webhook events |
- Full reference and selling models: DOC.md · DOC.UK.md
- Package API: pkg.go.dev/github.com/goloop/creem
- Changes between versions: CHANGELOG.md
- Credit wallets on top: goloop/ledger
Contributions are welcome. Please run go test -race ./..., go vet ./...
and gofmt -l . before submitting a pull request.
creem is released under the MIT License. See LICENSE.
Publish the existing payment and webhook API as version 1.0.0. The v1 release keeps the existing import path and public API. Future incompatible changes require a new major version.