> ## Documentation Index
> Fetch the complete documentation index at: https://docs.global-e.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get subscription and payment reference details (Merchant to Global-e)
> The merchant calls Global-e to return the current masked payment method and billing address per subscription ID, for display in the merchant portal. The response is a batch: one result per requested ID, each either with Data or with an Error.
**Server-to-server only.** The call to Global-e Web must be made server-to-server and never from the client side. The `merchantGuid` route parameter is a secret key that identifies the merchant and must not be exposed in browser-side code, client requests, or anywhere it could be intercepted. Keep it on the backend and issue this request from your server.
Part of the [Subscription Connector](/subscription-connector) integration guide — see it for when and how to use this endpoint.
## OpenAPI
````yaml api-reference/specs/getsubscriptionandpaymentreferencedetails.yaml GET /Payments/Subscriptions/{merchantGuid}
openapi: 3.0.3
info:
title: GetSubscriptionAndPaymentReferenceDetails
version: 1.0.0
description: >-
GetSubscriptionAndPaymentReferenceDetails is an HTTP GET endpoint that
returns subscription and payment-reference details for one or more
subscription IDs. It resolves the merchant by GUID, then for each
subscription ID returns (when available) subscription info plus masked
payment details (e.g. card suffix, expiry, vendor). The response is a batch:
one result per requested ID, each either with Data or with an Error.
servers:
- url: https://{globale_web_domain}
variables:
globale_web_domain:
default: globale_web_domain
description: >-
Global-e Web (GlobalE.Web) domain for your environment, supplied to
the merchant by Global-e.
security: []
tags:
- name: Subscriptions
description: Merchant to Global-e. Payments domain.
paths:
/Payments/Subscriptions/{merchantGuid}:
get:
tags:
- Subscriptions
summary: Get subscription and payment reference details
description: >-
Get subscription and payment reference details for the given merchant
and subscription IDs.
operationId: getSubscriptionAndPaymentReferenceDetails
parameters:
- name: merchantGuid
in: path
required: true
description: >-
Merchant GUID. Must be a valid GUID format. This is a secret API key
that identifies the merchant. Server-to-server only — it must not be
exposed in browser-side/client code, and this call must be made from
your server.
schema:
type: string
format: uuid
example: 00000000-0000-0000-0000-000000000001
- name: ids
in: query
required: true
description: >-
One or more subscription IDs. Typically sent as repeated query
params: ids=id1&ids=id2.
explode: true
style: form
schema:
type: array
minItems: 1
items:
type: string
example: sub-123
responses:
'200':
description: >-
Batch response: one result per requested subscription ID, in the
same order as requested.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchResponse'
examples:
resolved_result:
summary: One resolved result - Data present, Error null
value:
Results:
- SubscriptionId: sub-123
Data:
SubscriptionId: sub-123
CultureCode: en-US
BillingAddress: null
CardNumSuffix: '1234'
ExpMonth: 12
ExpYear: 2025
Vendor: VISA
Error: null
partial_success:
summary: Partial success - one Data, one Error
value:
Results:
- SubscriptionId: sub-123
Data:
SubscriptionId: sub-123
CultureCode: en-US
BillingAddress: null
CardNumSuffix: '1234'
ExpMonth: 12
ExpYear: 2025
Vendor: VISA
Error: null
- SubscriptionId: sub-456
Data: null
Error:
Code: NOT_FOUND
Message: Subscription not found
'400':
description: >-
Bad Request. Returned when merchantGuid is missing, is not a valid
GUID, when no subscription ID is supplied, or when no merchant is
found for the GUID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
merchant_guid_required:
summary: MerchantGUID missing
value:
Error: MerchantGUID is required and cannot be empty.
merchant_guid_invalid:
summary: MerchantGUID not a valid GUID
value:
Error: MerchantGUID '{merchantGuid}' is not a valid GUID format.
ids_required:
summary: No subscription ID supplied
value:
Error: >-
At least one subscriptionId is required in query
parameters.
merchant_not_found:
summary: Merchant not found for the GUID
value:
error: >-
Merchant not found for the provided MerchantGUID:
{merchantGuid}.
'500':
description: Internal Server Error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unexpected_error:
summary: Unexpected error retrieving subscription details
value:
Error: >-
Unexpected error occurred while retrieving subscription
details.
x-codeSamples:
- lang: curl
source: |-
curl -X GET \
"https://{globale_web_domain}/Payments/Subscriptions/00000000-0000-0000-0000-000000000001?ids=sub-123&ids=sub-456"
components:
schemas:
BatchResponse:
type: object
required:
- Results
properties:
Results:
type: array
description: >-
Array of one item per requested subscription ID, in the same order
as requested.
items:
$ref: '#/components/schemas/ResultItem'
ErrorResponse:
type: object
description: The endpoint returns JSON with an Error (or error) property.
properties:
Error:
type: string
description: Error message returned by Global-e.
error:
type: string
description: >-
Error message returned by Global-e. The merchant-lookup failure uses
this lower-case form.
ResultItem:
type: object
required:
- SubscriptionId
properties:
SubscriptionId:
type: string
description: The subscription ID that was requested.
example: sub-123
Data:
allOf:
- $ref: '#/components/schemas/SubscriptionData'
nullable: true
description: >-
Present when the subscription and payment reference could be
resolved.
Error:
allOf:
- $ref: '#/components/schemas/ResultError'
nullable: true
description: >-
Present when the item could not be resolved or processed. Has Code
and Message.
SubscriptionData:
type: object
description: Subscription details plus masked payment reference details.
properties:
SubscriptionId:
type: string
description: From subscription details.
example: sub-123
CultureCode:
type: string
description: From subscription details.
example: en-US
BillingAddress:
type: object
nullable: true
description: From subscription details.
CardNumSuffix:
type: string
nullable: true
description: >-
From payment reference (credit card). For non-credit-card methods,
card fields may be null.
example: '1234'
ExpMonth:
type: integer
nullable: true
description: >-
From payment reference (credit card). For non-credit-card methods,
card fields may be null.
example: 12
ExpYear:
type: integer
nullable: true
description: >-
From payment reference (credit card). For non-credit-card methods,
card fields may be null.
example: 2025
Vendor:
type: string
description: >-
From payment reference (credit card). For non-credit-card methods,
Vendor is the payment method display name.
example: VISA
ResultError:
type: object
required:
- Code
- Message
properties:
Code:
type: string
description: >-
Per-result error code. When a given subscription ID fails, that item
has Error set
and Data null. Typical codes:
| Code | Message (typical) |
| --- | --- |
| INVALID_INPUT | Subscription ID is null or empty |
| NOT_FOUND | Subscription not found |
| PROCESSING_ERROR | PaymentReference is empty / Payment details
missing / Specific payment details missing / Error processing
payment details / Unexpectedly failed to process the request or
payment details |
enum:
- INVALID_INPUT
- NOT_FOUND
- PROCESSING_ERROR
example: NOT_FOUND
Message:
type: string
description: Message describing why the item could not be resolved or processed.
example: Subscription not found
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.