---
title: "Set your payout details"
method: PUT
path: "/v1/me/partner/payout-details"
tags: ["Partner Program"]
---

# Set your payout details

`PUT /v1/me/partner/payout-details`

## Request

- Base URL: `https://api.subscriby.net`
- URL: `https://api.subscriby.net/v1/me/partner/payout-details`
- Auth: HTTP bearer

```bash
curl -X PUT https://api.subscriby.net/v1/me/partner/payout-details \
  -H "Authorization: Bearer $SUBSCRIBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "paypal",
    "details": "ada@example.com",
    "legal_name": "Ada Lovelace",
    "tax_country": "GB",
    "us_person": false,
    "accept_terms": true
  }'
```

Writes how you are paid: the rail, what it pays to, and the tax declaration every cash rail needs. `paypal` and `crypto` take their one `details` (the PayPal email, the USDT TRC20 wallet address); `wise` and `remitly` take the bank account (`bank_holder`, `bank_name`, `bank_country`, `bank_account_number`, and `bank_swift`, `bank_branch_code`, `bank_address` when the transfer needs them); `credit` takes nothing and is accepted while that rail is open. Only the destination the chosen rail uses is kept, encrypted; a rail you leave behind keeps nothing on file. The response is the partner object with `payout_method` and `payout_details_complete` updated and the destination absent.

> **The terms come first.** A rail cannot be saved until you have accepted the Partner Program Terms: send `accept_terms: true` here, or call the terms endpoint before.

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- UpdatePartnerPayoutDetailsRequest: The rail to be paid by, what it pays to, and the tax declaration. Only the destination the chosen rail uses is kept; a rail left behind keeps nothing on file.
  - `method` 'credit' | 'paypal' | 'wise' | 'remitly' | 'crypto', required: How a partner takes what the Partner Program owes them. Credit needs nothing typed: an approved commission is applied to the partner's own Stripe balance and offsets their next invoices. The four cash rails are paid by the owner by hand: PayPal and USDT to one typed detail (an email, a wallet address), Wise and Remitly into a bank account (the holder, the bank, its country, the account number, and the codes some transfers need). Either is the partner's money, so it is stored encrypted and never announced. Whatever a rail charges to carry the money comes out of the payout, which the terms say in so many words.
  - `details` string, nullable: What a single-detail rail pays to: the PayPal email for `paypal`, the wallet address for `crypto`. Required on those rails, ignored on the others. At most 190 characters.
  - `bank_holder` string, nullable: The name on the bank account, for `wise` and `remitly`. At most 120 characters.
  - `bank_name` string, nullable: The bank, for `wise` and `remitly`. At most 120 characters.
  - `bank_country` string, nullable: Where the bank is, as an ISO 3166-1 alpha-2 code, for `wise` and `remitly`.
  - `bank_account_number` string, nullable: The account number or IBAN, for `wise` and `remitly`: letters, digits, spaces and dashes, at most 40 characters.
  - `bank_swift` string, nullable: The SWIFT or BIC code, when the bank has one: 8 or 11 characters.
  - `bank_branch_code` string, nullable: The branch, routing, sort or IFSC code, when the transfer needs one: letters, digits, spaces and dashes, at most 20 characters.
  - `bank_address` string, nullable: The account holder's address, when the transfer needs one. At most 200 characters.
  - `legal_name` string, nullable: The name a payment is made out to. Required on every cash rail. At most 120 characters.
  - `tax_country` string, nullable: The country of tax residence, as an ISO 3166-1 alpha-2 code. Required on every cash rail.
  - `us_person` boolean, nullable: Whether you are a US person for tax purposes.
  - `accept_terms` boolean: Send `true` to accept the Partner Program Terms with this save. A rail cannot be saved until the terms are accepted, here or through the terms endpoint.

## Response `200`

The partner object after the change.

- object
  - `data` PartnerResource, required: The caller's standing in the Partner Program: the application's state, the code and the links once approved, the commission ladder, how many creators they referred and converted, what they have earned, and how they are paid; never the payout destination itself.
    - `id` string, required: The partnership's id. A creator holds one.
    - `status` string, required: `applied` (under review by Subscriby), `active` (approved and earning), `rejected` (not approved; `reapply_available_at` says when they may apply again) or `suspended` (approved, but the link no longer attributes and nothing new is earned).
    - `code` string, nullable, required: The partner code, seven characters, carried by every link and typeable on the sign-up form; null until approved.
    - `links` object, nullable, required: The addresses to hand out; null until approved.
      - `web` string, required: The web link: sets the attribution cookie and lands on the marketing site with the friend offer shown.
      - `connectors` object[], required: One deep link per connector whose bot signs creators up, each opening the sign-up conversation with the code attached.
        - `connector` string, required: The connector key.
        - `name` string, required: The connector's name, for a label.
        - `url` string, required: The deep link.
    - `commission_percent` string, nullable, required: The rate the partner earns on every invoice of a creator who converts from now on, as a decimal string with two places: `"15.00"`. Null until approved.
    - `base_percent` integer, required: Where every partner starts, whole percent.
    - `max_percent` integer, required: The ladder's cap, whole percent.
    - `commitment_points` integer, nullable, required: Points the verified commitments add; null until approved.
    - `volume_points` integer, nullable, required: Points the volume tiers reached add; null until approved.
    - `paying_referrals` integer, nullable, required: How many referred creators have converted, the figure the volume tiers read; null until approved.
    - `next_tier_at` integer, nullable, required: The paying-referral count of the next volume tier; null past the last, or until approved.
    - `next_tier_points` integer, nullable, required: What that tier adds; null past the last, or until approved.
    - `commission_months` integer, required: How long a commission runs after each conversion, in months.
    - `hold_days` integer, required: Days a commission waits before it is payable, so a refund inside the window can take it back.
    - `minimum_cash_payout` string, required: The balance a cash rail reaches before Subscriby pays, in USD, as a whole-number string.
    - `friend_discount_percent` integer, required: The discount a referred creator gets on their first paid months, whole percent.
    - `friend_discount_months` integer, required: How many of their first months the discount covers.
    - `currency` string, required: The ISO 4217 code every balance is in. Platform invoices are USD, so it is `USD`.
    - `clicks` integer, required: How many visits the web link has brought.
    - `referrals` object, required: How many creators the partner brought in, by state.
      - `total` integer, required: Every referral recorded.
      - `signed_up` integer, required: Signed up, not yet on a paid plan, inside their conversion window.
      - `converted` integer, required: Paid their first Starter or Growth invoice and earning.
      - `under_review` integer, required: Held by Subscriby for a fraud signal; earning nothing until cleared.
      - `expired` integer, required: Never paid inside the window.
      - `rejected` integer, required: Rejected after review.
    - `balance` object, nullable, required: What the partner has earned, as decimal strings with four places in `currency`; null until approved.
      - `pending` string, required: Commissions still inside the hold.
      - `payable` string, required: Approved and not yet settled, clawbacks netted: what the next credit or payout covers.
      - `credited` string, required: Settled as Subscriby Credit on the partner's own invoices.
      - `paid` string, required: Paid out in cash.
      - `earned` string, required: Everything earned: pending, payable, credited and paid together.
    - `payout_method` string, nullable, required: The rail the partner chose: `credit` (Subscriby Credit on their own invoices), `paypal`, `wise`, `remitly` or `crypto` (USDT on TRC20); null until chosen.
    - `payout_details_complete` boolean, required: Whether the rail has everything a payment needs. The destination itself (the PayPal address, the wallet, the bank account) is never returned.
    - `legal_name` string, nullable, required: The name a payment is made out to, as declared; null until declared.
    - `tax_country` string, nullable, required: The country of tax residence, as an ISO 3166-1 alpha-2 code; null until declared.
    - `us_person` boolean, nullable, required: Whether the partner declared themselves a US person for tax purposes; null until declared.
    - `terms_accepted_at` string, nullable, required: When the partner last accepted the Partner Program Terms, ISO 8601; null until accepted.
    - `terms_version` string, nullable, required: The version of the terms accepted, as a date; null until accepted.
    - `commitments` unknown[], required: The promotion commitments the partner made, in the order promised, each with its proof state.
      - unknown
    - `applied_at` string, required: When the application was filed, ISO 8601.
    - `joined_at` string, nullable, required: When Subscriby approved it, ISO 8601; null until then.
    - `rejected_at` string, nullable, required: When Subscriby declined it, ISO 8601; null otherwise.
    - `rejection_reason` string, nullable, required: Why it was declined, in Subscriby's words; null otherwise.
    - `reapply_available_at` string, nullable, required: When a declined applicant may apply again, ISO 8601; null when they may now, or were not declined.
    - `suspended_at` string, nullable, required: When the partnership was suspended, ISO 8601; null while it stands.
    - `created_at` string, nullable, required: When the row was written, ISO 8601.
    - `updated_at` string, nullable, required: When it last changed, ISO 8601.

## Other responses

- `400`: `IDEMPOTENCY_KEY_MISSING`: every write needs an `Idempotency-Key` header. Send a fresh UUID per distinct operation.
- `401`: `AUTHENTICATION_REQUIRED`: the request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an `sbt_test_` token on production).
- `403`: `TOKEN_MISSING_ABILITY`: the token is valid but does not carry the ability this endpoint requires; `error.context.required_ability` names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers `FORBIDDEN`, `TEAM_TIER_REQUIRED` or `CONNECTOR_TIER_REQUIRED` with the same status, and says so in its own description.
- `404`: `RESOURCE_NOT_FOUND`: until the caller applies.
- `409`: `IDEMPOTENCY_KEY_REUSED`: the key was already used in the last 24 hours with a different request body.
- `422`: `VALIDATION_FAILED`: the payload broke a rule, and `error.fields` maps each offending key to its messages. A refusal from the domain, such as a plan that cannot go on sale or a member who cannot be removed, uses the same code with `error.message` saying why and no `fields`. On this endpoint: `VALIDATION_FAILED`: when a field is invalid or missing for the rail, when the terms are not accepted, when the credit rail is closed, when the bank account is incomplete, or while the application is under review or was declined.
- `425`: `IDEMPOTENCY_REPLAY_IN_PROGRESS`: the first request with this key is still running; retry in a few seconds and the original response is replayed.
- `429`: `RATE_LIMITED`: the token has spent its 300 requests a minute or 10,000 an hour; `Retry-After` says when the next one is accepted.

---

[API](https://skmtc.dev/memberpass/apis/subscriby-rest-api.md) · [All operations](https://skmtc.dev/memberpass/apis/subscriby-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/memberpass/apis/subscriby-rest-api/revisions/59c4df91d764?raw)