Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Create a payment link 

Creates a payment link.

Parameters

  • line_itemsarray of dictionariesRequired

    The line items representing what is being sold. Each line item represents an item being sold. Up to 20 line items are supported.

  • metadatadictionary

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. Metadata associated with this Payment Link will automatically be copied to checkout sessions created by this payment link.

More parameters

  • after_completiondictionary

  • allow_promotion_codesboolean

  • application_fee_amountintegerConnect only

  • application_fee_percentfloatConnect only

  • automatic_taxdictionary

  • billing_address_collectionenum

  • consent_collectiondictionary

  • currencyenum

  • custom_fieldsarray of dictionaries

  • custom_textdictionary

  • customer_creationenum

  • inactive_messagestring

  • invoice_creationdictionary

  • on_behalf_ofstringConnect only

  • optional_itemsarray of dictionaries

  • payment_intent_datadictionary

  • payment_method_collectionenum

  • payment_method_typesarray of enums

  • phone_number_collectiondictionary

  • restrictionsdictionary

  • shipping_address_collectiondictionary

  • shipping_optionsarray of dictionaries

  • submit_typeenum

  • subscription_datadictionary

  • tax_id_collectiondictionary

  • transfer_datadictionaryConnect only

Returns

Returns the payment link.

POST /v1/payment_links
curl https://api.stripe.com/v1/payment_links \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "line_items[0][price]"=price_1MoC3TLkdIwHu7ixcIbKelAC \
  -d "line_items[0][quantity]"=1
Response
{
  "id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
  "object": "payment_link",
  "active": true,
  "after_completion": {
    "hosted_confirmation": {
      "custom_message": null
    },
    "type": "hosted_confirmation"
  },
  "allow_promotion_codes": false,
  "application_fee_amount": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": null
  },
  "billing_address_collection": "auto",
  "consent_collection": null,
  "currency": "usd",
  "custom_fields": [],
  "custom_text": {
    "shipping_address": null,
    "submit": null
  },
  "customer_creation": "if_required",
  "invoice_creation": {
    "enabled": false,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": null,
      "metadata": {},
      "rendering_options": null
    }
  },
  "livemode": false,
  "metadata": {},
  "on_behalf_of": null,
  "payment_intent_data": null,
  "payment_method_collection": "always",
  "payment_method_types": null,
  "phone_number_collection": {
    "enabled": false
  },
  "shipping_address_collection": null,
  "shipping_options": [],
  "submit_type": "auto",
  "subscription_data": {
    "description": null,
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "trial_period_days": null
  },
  "tax_id_collection": {
    "enabled": false
  },
  "transfer_data": null,
  "url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
}

Update a payment link 

Updates a payment link.

Parameters

  • activeboolean

    Whether the payment link’s url is active. If false, customers visiting the URL will be shown a page saying that the link has been deactivated.

  • line_itemsarray of dictionaries

    The line items representing what is being sold. Each line item represents an item being sold. Up to 20 line items are supported.

  • metadatadictionary

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. Metadata associated with this Payment Link will automatically be copied to checkout sessions created by this payment link.

More parameters

  • after_completiondictionary

  • allow_promotion_codesboolean

  • automatic_taxdictionary

  • billing_address_collectionenum

  • custom_fieldsarray of dictionaries

  • custom_textdictionary

  • customer_creationenum

  • inactive_messagestring

  • invoice_creationdictionary

  • payment_intent_datadictionary

  • payment_method_collectionenum

  • payment_method_typesarray of enums

  • phone_number_collectiondictionary

  • restrictionsdictionary

  • shipping_address_collectiondictionary

  • submit_typeenum

  • subscription_datadictionary

  • tax_id_collectiondictionary

Returns

Updated payment link.

POST /v1/payment_links/:id
curl https://api.stripe.com/v1/payment_links/plink_1MoC3ULkdIwHu7ixZjtGpVl2 \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "metadata[order_id]"=6735
Response
{
  "id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
  "object": "payment_link",
  "active": true,
  "after_completion": {
    "hosted_confirmation": {
      "custom_message": null
    },
    "type": "hosted_confirmation"
  },
  "allow_promotion_codes": false,
  "application_fee_amount": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": null
  },
  "billing_address_collection": "auto",
  "consent_collection": null,
  "currency": "usd",
  "custom_fields": [],
  "custom_text": {
    "shipping_address": null,
    "submit": null
  },
  "customer_creation": "if_required",
  "invoice_creation": {
    "enabled": false,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": null,
      "metadata": {},
      "rendering_options": null
    }
  },
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "on_behalf_of": null,
  "payment_intent_data": null,
  "payment_method_collection": "always",
  "payment_method_types": null,
  "phone_number_collection": {
    "enabled": false
  },
  "shipping_address_collection": null,
  "shipping_options": [],
  "submit_type": "auto",
  "subscription_data": {
    "description": null,
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "trial_period_days": null
  },
  "tax_id_collection": {
    "enabled": false
  },
  "transfer_data": null,
  "url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
}

Retrieve a payment link's line items 

When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Parameters

No parameters.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit payment link line items, starting after Line Item starting_after. Each entry in the array is a separate Line Item object. If no more line items are available, the resulting array will be empty.

GET /v1/payment_links/:id/line_items
curl https://api.stripe.com/v1/payment_links/plink_1N4CWjLkdIwHu7ix2Y2F1kqb/line_items \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "object": "list",
  "data": [
    {
      "id": "li_NpsHNiHSaDeU0X",
      "object": "item",
      "amount_discount": 0,
      "amount_subtotal": 1099,
      "amount_tax": 0,
      "amount_total": 1099,
      "currency": "usd",
      "description": "T-shirt",
      "price": {
        "id": "price_1N4AEsLkdIwHu7ix7Ssho8Cl",
        "object": "price",
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1683237782,
        "currency": "usd",
        "custom_unit_amount": null,
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "product": "prod_NppuJWzzNnD5Ut",
        "recurring": null,
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": null,
        "type": "one_time",
        "unit_amount": 1099,
        "unit_amount_decimal": "1099"
      },
      "quantity": 1
    }
  ],
  "has_more": false,
  "url": "/v1/payment_links/plink_1N4CWjLkdIwHu7ix2Y2F1kqb/line_items"
}

Retrieve payment link 

Retrieve a payment link.

Parameters

No parameters.

Returns

Returns the payment link.

GET /v1/payment_links/:id
curl https://api.stripe.com/v1/payment_links/plink_1MoC3ULkdIwHu7ixZjtGpVl2 \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
  "object": "payment_link",
  "active": true,
  "after_completion": {
    "hosted_confirmation": {
      "custom_message": null
    },
    "type": "hosted_confirmation"
  },
  "allow_promotion_codes": false,
  "application_fee_amount": null,
  "application_fee_percent": null,
  "automatic_tax": {
    "enabled": false,
    "liability": null
  },
  "billing_address_collection": "auto",
  "consent_collection": null,
  "currency": "usd",
  "custom_fields": [],
  "custom_text": {
    "shipping_address": null,
    "submit": null
  },
  "customer_creation": "if_required",
  "invoice_creation": {
    "enabled": false,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": null,
      "metadata": {},
      "rendering_options": null
    }
  },
  "livemode": false,
  "metadata": {},
  "on_behalf_of": null,
  "payment_intent_data": null,
  "payment_method_collection": "always",
  "payment_method_types": null,
  "phone_number_collection": {
    "enabled": false
  },
  "shipping_address_collection": null,
  "shipping_options": [],
  "submit_type": "auto",
  "subscription_data": {
    "description": null,
    "invoice_settings": {
      "issuer": {
        "type": "self"
      }
    },
    "trial_period_days": null
  },
  "tax_id_collection": {
    "enabled": false
  },
  "transfer_data": null,
  "url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
}

List all payment links 

Returns a list of your payment links.

Parameters

  • activeboolean

    Only return payment links that are active or inactive (e.g., pass false to list all inactive payment links).

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit payment links, starting after payment link starting_after. Each entry in the array is a separate payment link object. If no more payment links are available, the resulting array will be empty. This request should never return an error.

GET /v1/payment_links
curl -G https://api.stripe.com/v1/payment_links \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/payment_links",
  "has_more": false,
  "data": [
    {
      "id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
      "object": "payment_link",
      "active": true,
      "after_completion": {
        "hosted_confirmation": {
          "custom_message": null
        },
        "type": "hosted_confirmation"
      },
      "allow_promotion_codes": false,
      "application_fee_amount": null,
      "application_fee_percent": null,
      "automatic_tax": {
        "enabled": false,
        "liability": null
      },
      "billing_address_collection": "auto",
      "consent_collection": null,
      "currency": "usd",
      "custom_fields": [],
      "custom_text": {
        "shipping_address": null,
        "submit": null
      },
      "customer_creation": "if_required",
      "invoice_creation": {
        "enabled": false,
        "invoice_data": {
          "account_tax_ids": null,
          "custom_fields": null,
          "description": null,
          "footer": null,
          "issuer": null,
          "metadata": {},
          "rendering_options": null
        }
      },
      "livemode": false,
      "metadata": {},
      "on_behalf_of": null,
      "payment_intent_data": null,
      "payment_method_collection": "always",
      "payment_method_types": null,
      "phone_number_collection": {
        "enabled": false
      },
      "shipping_address_collection": null,
      "shipping_options": [],
      "submit_type": "auto",
      "subscription_data": {
        "description": null,
        "invoice_settings": {
          "issuer": {
            "type": "self"
          }
        },
        "trial_period_days": null
      },
      "tax_id_collection": {
        "enabled": false
      },
      "transfer_data": null,
      "url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
    }
  ]
}