> ## Documentation Index > Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a customer's subscription details > Retrieve the details of a customer's subscriptions, wallet balances and links to top up or increase subscription quantities. ## OpenAPI ````yaml GET /api/v1/customers/{customer_key}/details openapi: 3.0.1 info: title: Metrifox API Documentation version: v1 description: >- Welcome to Metrifox Platform's API documentation. This comprehensive API suite enables seamless integration with our platform, providing secure and efficient access to our services. servers: - url: https://{defaultHost} variables: defaultHost: default: api.metrifox.com security: - api_key: [] paths: /api/v1/customers/{customer_key}/details: get: tags: - Customers summary: Get customer subscription details description: > Retrieves a customer's subscription-related details, including their active and historical subscriptions, wallet balances, payment methods, and hosted self-service URLs you can link customers to (e.g. to top up a wallet, manage add-ons, or update subscription item quantities). Use this endpoint when you want everything you need to build a customer-facing billing view in one call. For granular usage data per feature, use `GET /api/v1/subscriptions/{id}/entitlements-usage` or `/entitlements-summary`. **Returns:** - Customer basic information (`metrifox_id`, `customer_key`, `customer_type`, contact details) - Billing configuration (`billing_email`, `billing_address`, `currency`, `timezone`, `language`) - `wallets` — the customer's credit wallets across all their subscriptions, each with a `topup_link` you can open in the browser - `subscriptions` — grouped by product, each containing: - The current subscription with billing info, `update_quantity_link`, and `manage_addons_link` - `subscriptions_history` — prior subscriptions on the same product - `payment_method` — the payment method attached to the subscription operationId: getCustomerDetails parameters: - name: customer_key in: path required: true description: >- The unique identifier of the customer on your platform, saved as customer_key on Metrifox schema: type: string example: cust-mljp3ra6ffjm responses: '200': description: Customer details fetched successfully content: application/json: schema: $ref: '#/components/schemas/CustomerDetailsResponse' examples: customer_details: summary: Customer Details Response value: statusCode: 200 message: Customer Details Fetched Successfully meta: {} data: metrifox_id: fa545755-be20-4d1b-85d0-a2265dd52c56 customer_key: cust-mljp3ra6ffjm customer_type: INDIVIDUAL primary_email: uppender@yopmail.com display_name: Uppender Lala full_name: Uppender Lala billing_email: uppender@yopmail.com billing_address: null currency: USD timezone: null language: null tenant_checkout_username: metrifox-inc wallets: - id: b7bf0d46-9f7d-4d58-9bb4-6bfb2d3e6a5c name: Image Credits credit_key: image_credits credit_system_id: c17f9a7b-1e49-4f80-9b6e-8d85b4a11f8a credit_unit_singular: credit credit_unit_plural: credits balance: 120 low_balance_threshold: 20 credit_attachment_id: fb4e18f0-8b9c-4977-9fdd-7a4b76b2e8d3 customer_key: cust-mljp3ra6ffjm allocations: [] topup_link: >- https://app.metrifox.com/metrifox-inc/wallets/b7bf0d46-9f7d-4d58-9bb4-6bfb2d3e6a5c?customer=cust-mljp3ra6ffjm subscriptions: - product_key: product_deliveroo_df37 product_name: Deliveroo status: active subscription: can_update_quantities: true update_quantity_link: >- https://app.metrifox.com/metrifox-inc/plan_basic-less_plan_timf/subscriptions/625f5cee-259b-4994-b7eb-416b9e551f2c?customer=cust-mljp3ra6ffjm manage_addons_link: >- https://app.metrifox.com/metrifox-inc/plan_basic-less_plan_timf/addons?customer=cust-mljp3ra6ffjm&subscription=625f5cee-259b-4994-b7eb-416b9e551f2c id: 625f5cee-259b-4994-b7eb-416b9e551f2c status: active starts_at: '2026-02-13T13:01:17.828Z' ends_at: null cancelled_at: null renews_at: '2026-03-12T16:55:21.847Z' trial_end_date: null post_trial_action: null plan_name: Basic-less Plan plan_version: 2 default_plan_id: null default_plan_name: null product_name: Deliveroo product_key: product_deliveroo_df37 offering_key: plan_basic-less_plan_timf currency_code: USD created_at: '2026-02-13T13:01:18.434Z' next_billing_date: Mar 12, 2026 next_billing_amount: 21 current_billing_period_start: '2026-02-13T13:01:17.828Z' current_billing_period_end: '2026-03-12T16:55:21.847Z' subscription_items: - price_option_id: a746f6e4-a2a0-4d72-9012-cb1815478331 name: Basic-less Plan quantity: 1 unit_price: 15 total_amount: 15 billing_period_start: '2026-02-13T13:01:17.828Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: ProductCatalogues::Offerings::Plan source_id: 9ecf5f02-445b-43de-a12f-168aa4a4a1fa - price_option_id: 862048ae-6d2c-41ad-9fa9-924d45eed9aa name: Seats quantity: 3 unit_price: null total_amount: 3 billing_period_start: '2026-02-13T13:01:17.828Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: >- ProductCatalogues::Entitlements::PaidEntitlement source_id: 262bd36c-eef8-4981-8c58-52c952d3f42e - price_option_id: 4ff36eea-ca4f-4fa7-9294-e744d9ba056d name: Skills Audit quantity: 2 unit_price: null total_amount: 3 billing_period_start: '2026-02-13T13:01:17.828Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: >- ProductCatalogues::Entitlements::PaidEntitlement source_id: 20910dfa-4a88-451c-9b85-2ed8ba937e97 upcoming_invoice: invoice_id: 0d9e5a0e-7de4-48c6-b01a-b1759394578b invoice_number: null amount: '21.0' currency: id: 4c1a44b7-7369-4415-84f7-2a5bab99932b code: USD name: US Dollar country: United States of America decimal_places: 2 symbol: $ is_active: true base_unit_name: cents base_unit_per_standard: 100 created_at: '2025-11-17T00:33:16.053Z' updated_at: '2025-11-17T00:33:16.053Z' country_code: US due_date: '2026-04-01T23:59:59.999Z' status: draft subscriptions_history: - can_update_quantities: true update_quantity_link: >- https://app.metrifox.com/metrifox-inc/plan_basic-less_plan_timf/subscriptions/625f5cee-259b-4994-b7eb-416b9e551f2c?customer=cust-mljp3ra6ffjm manage_addons_link: >- https://app.metrifox.com/metrifox-inc/plan_basic-less_plan_timf/addons?customer=cust-mljp3ra6ffjm&subscription=625f5cee-259b-4994-b7eb-416b9e551f2c id: 625f5cee-259b-4994-b7eb-416b9e551f2c status: active starts_at: '2026-02-13T13:01:17.828Z' ends_at: null cancelled_at: null renews_at: '2026-03-12T16:55:21.847Z' trial_end_date: null post_trial_action: null plan_name: Basic-less Plan plan_version: 2 default_plan_id: null default_plan_name: null product_name: Deliveroo product_key: product_deliveroo_df37 offering_key: plan_basic-less_plan_timf currency_code: USD created_at: '2026-02-13T13:01:18.434Z' next_billing_date: Mar 12, 2026 next_billing_amount: 21 current_billing_period_start: '2026-02-13T13:01:17.828Z' current_billing_period_end: '2026-03-12T16:55:21.847Z' subscription_items: - price_option_id: a746f6e4-a2a0-4d72-9012-cb1815478331 name: Basic-less Plan quantity: 1 unit_price: 15 total_amount: 15 billing_period_start: '2026-02-13T13:01:17.828Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: ProductCatalogues::Offerings::Plan source_id: 9ecf5f02-445b-43de-a12f-168aa4a4a1fa - price_option_id: 862048ae-6d2c-41ad-9fa9-924d45eed9aa name: Seats quantity: 3 unit_price: null total_amount: 3 billing_period_start: '2026-02-13T13:01:17.828Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: >- ProductCatalogues::Entitlements::PaidEntitlement source_id: 262bd36c-eef8-4981-8c58-52c952d3f42e - price_option_id: 4ff36eea-ca4f-4fa7-9294-e744d9ba056d name: Skills Audit quantity: 2 unit_price: null total_amount: 3 billing_period_start: '2026-02-13T13:01:17.828Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: >- ProductCatalogues::Entitlements::PaidEntitlement source_id: 20910dfa-4a88-451c-9b85-2ed8ba937e97 upcoming_invoice: invoice_id: 0d9e5a0e-7de4-48c6-b01a-b1759394578b invoice_number: null amount: '21.0' currency: id: 4c1a44b7-7369-4415-84f7-2a5bab99932b code: USD name: US Dollar country: United States of America decimal_places: 2 symbol: $ is_active: true base_unit_name: cents base_unit_per_standard: 100 created_at: '2025-11-17T00:33:16.053Z' updated_at: '2025-11-17T00:33:16.053Z' country_code: US due_date: '2026-04-01T23:59:59.999Z' status: draft - can_update_quantities: true update_quantity_link: >- https://app.metrifox.com/metrifox-inc/plan_basic-less_plan_timf/subscriptions/c541c94a-6a02-4bc0-bf8b-1a5a4245e1d8?customer=cust-mljp3ra6ffjm manage_addons_link: >- https://app.metrifox.com/metrifox-inc/plan_basic-less_plan_timf/addons?customer=cust-mljp3ra6ffjm&subscription=c541c94a-6a02-4bc0-bf8b-1a5a4245e1d8 id: c541c94a-6a02-4bc0-bf8b-1a5a4245e1d8 status: deactivated starts_at: '2026-02-12T16:55:21.847Z' ends_at: '2026-02-13T13:01:13.118Z' cancelled_at: '2026-02-13T13:01:13.116Z' renews_at: '2026-03-12T16:55:25.679Z' trial_end_date: null post_trial_action: null plan_name: Basic Plan plan_version: 2 default_plan_id: null default_plan_name: null product_name: Deliveroo product_key: product_deliveroo_df37 offering_key: plan_basic_plan_fzx4 currency_code: USD created_at: '2026-02-12T16:55:22.468Z' next_billing_date: Mar 12, 2026 next_billing_amount: 35 current_billing_period_start: '2026-02-12T16:55:21.847Z' current_billing_period_end: '2026-03-12T16:55:21.847Z' subscription_items: - price_option_id: f97c478b-bea7-4ec1-b40a-186d9a61a8b7 name: Basic Plan quantity: 1 unit_price: 20 total_amount: 20 billing_period_start: '2026-02-12T16:55:21.847Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: ProductCatalogues::Offerings::Plan source_id: 20da23ab-3262-456b-a577-d517918f8d3f - price_option_id: 6d4a043b-186d-4d20-98c2-c5226c5a27c3 name: Seats quantity: 5 unit_price: null total_amount: 25 billing_period_start: '2026-02-12T16:55:21.847Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: >- ProductCatalogues::Entitlements::PaidEntitlement source_id: ce08372d-dc3e-4f6d-99d1-9b481ee77348 - price_option_id: dc0f2ae9-b362-49d2-b2a6-bf78ae0a756f name: Skills Audit quantity: 4 unit_price: null total_amount: 12 billing_period_start: '2026-02-12T16:55:21.847Z' billing_period_end: '2026-03-12T16:55:21.847Z' line_source_type: SubscriptionItem is_addon: false pricing: null currency_code: USD source_type: >- ProductCatalogues::Entitlements::PaidEntitlement source_id: 1336591e-cf5d-49f7-8ca1-696cbd0f2a82 upcoming_invoice: invoice_id: 01052f5e-a018-4aad-a73e-1140f3da060c invoice_number: null amount: '35.0' currency: id: 4c1a44b7-7369-4415-84f7-2a5bab99932b code: USD name: US Dollar country: United States of America decimal_places: 2 symbol: $ is_active: true base_unit_name: cents base_unit_per_standard: 100 created_at: '2025-11-17T00:33:16.053Z' updated_at: '2025-11-17T00:33:16.053Z' country_code: US due_date: '2026-04-01T23:59:59.999Z' status: draft payment_method: null errors: {} '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Customer not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 404 message: Customer not found errors: customer_key: - Customer with key 'cust-mljp3ra6ffjm' does not exist x-codeSamples: - lang: python label: Python SDK source: > from metrifox_sdk import MetrifoxClient client = MetrifoxClient(api_key="your_api_key") # Get customer details customer_key = "cust-mljp3ra6ffjm" response = client.customers.get_details(customer_key) print(f"Customer info: {response['data']['customer_key']}, {response['data']['primary_email']}") print(f"Product subscriptions: {response['data']['subscriptions']}") print(f"Wallets: {response['data']['wallets']}") # Access details for each product subscription for product_sub in response['data']['subscriptions']: print(f"Product: {product_sub['product_name']}") print(f"Subscription: {product_sub['subscription']}") - lang: javascript label: Javascript SDK source: > import { init } from "metrifox-js"; const metrifoxClient = init({ apiKey: process.env.METRIFOX_API_KEY }); // Get customer details const customerKey = "cust-mljp3ra6ffjm"; const response = await metrifoxClient.customers.getDetails(customerKey); console.log("Customer info:", response.data.customer_key, response.data.primary_email); console.log("Product subscriptions:", response.data.subscriptions); console.log("Wallets:", response.data.wallets); // Access details for each product subscription response.data.subscriptions.forEach(productSub => { console.log(`Product: ${productSub.product_name}`); console.log(`Subscription:`, productSub.subscription); }); - lang: ruby label: Ruby SDK source: > require 'metrifox-sdk' # Initialize with configuration METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" }) # Get customer details customer_key = "cust-mljp3ra6ffjm" response = METRIFOX_SDK.customers.get_details({ customer_key: customer_key }) puts "Customer info: #{response['data']['customer_key']}, #{response['data']['primary_email']}" puts "Product subscriptions: #{response['data']['subscriptions']}" puts "Wallets: #{response['data']['wallets']}" # Access details for each product subscription response['data']['subscriptions'].each do |product_sub| puts "Product: #{product_sub['product_name']}" puts "Subscription: #{product_sub['subscription']}" end components: schemas: CustomerDetailsResponse: type: object properties: statusCode: type: integer example: 200 message: type: string example: Customer Details Fetched Successfully meta: type: object additionalProperties: true description: Additional metadata data: $ref: '#/components/schemas/CustomerDetails' errors: type: object additionalProperties: true description: Any errors that occurred ErrorResponse: type: object properties: message: type: string description: Error message errors: type: object additionalProperties: true description: Detailed error information CustomerDetails: type: object properties: metrifox_id: type: string format: uuid description: Unique customer identifier in Metrifox system customer_key: type: string description: Customer key in your application customer_type: type: string description: Type of customer (BUSINESS or INDIVIDUAL) primary_email: type: string format: email nullable: true description: Primary email address for the customer display_name: type: string nullable: true description: Display name of the customer full_name: type: string nullable: true description: Full name of the customer billing_email: type: string format: email nullable: true description: Email address for billing communications billing_address: allOf: - $ref: '#/components/schemas/BillingAddress' nullable: true description: Billing address information currency: type: string nullable: true description: Preferred currency for billing timezone: type: string nullable: true description: Customer's timezone language: type: string nullable: true description: Preferred language for communications tenant_checkout_username: type: string description: Username for tenant checkout subscriptions: type: array items: $ref: '#/components/schemas/CustomerProductSubscription' description: Array of product subscriptions with their details wallets: type: array items: $ref: '#/components/schemas/CreditWallet' description: >- The customer's credit wallets across all their subscriptions, each with a topup_link you can open in the browser BillingAddress: type: object properties: line1: type: string description: First line of billing address line2: type: string description: Second line of billing address city: type: string description: City state: type: string description: State or province postal_code: type: string description: Postal/ZIP code country: type: string description: Country code additionalProperties: true CustomerProductSubscription: type: object properties: product_key: type: string description: Unique identifier for the product product_name: type: string description: Name of the product status: type: string description: Overall status of customer's relationship with this product subscription: $ref: '#/components/schemas/SubscriptionView' subscriptions_history: type: array items: $ref: '#/components/schemas/SubscriptionView' description: Historical subscriptions for this product payment_method: allOf: - $ref: '#/components/schemas/PaymentMethodDetails' nullable: true description: Payment method used for this product subscription CreditWallet: type: object properties: id: type: string description: Unique wallet identifier name: type: string description: Name of the wallet (inherited from the credit system) credit_key: type: string description: Unique key for the credit system this wallet belongs to credit_system_id: type: string description: ID of the credit system this wallet belongs to credit_unit_singular: type: string description: Singular form of the credit unit name credit_unit_plural: type: string description: Plural form of the credit unit name balance: type: number description: Current balance in the wallet low_balance_threshold: type: number nullable: true description: >- Threshold below which a low-balance signal is emitted (or nil if unset) credit_attachment_id: type: string nullable: true description: ID of the credit attachment currently provisioning into this wallet customer_key: type: string nullable: true description: Customer key this wallet belongs to allocations: type: array items: type: object additionalProperties: true description: >- Array of credit allocations (currently returned as an empty array for this endpoint) topup_link: type: string nullable: true description: >- Metrifox-hosted URL you can open in the browser to let the customer top up this wallet. Requires the tenant to have a checkout_username configured. SubscriptionView: type: object properties: can_update_quantities: type: boolean default: false description: Whether subscription quantities can be updated update_quantity_link: type: string format: uri nullable: true description: >- Metrifox-hosted URL you can open in the browser to let the customer update quantities on subscription items (null if quantity updates are not available for this plan). manage_addons_link: type: string format: uri nullable: true description: >- Metrifox-hosted URL you can open in the browser to let the customer add or remove add-ons on this subscription. id: type: string description: Unique subscription identifier status: type: string description: Subscription status starts_at: type: string format: date-time description: When the subscription starts ends_at: type: string format: date-time nullable: true description: When the subscription ends (null for active subscriptions) cancelled_at: type: string format: date-time nullable: true description: When the subscription was cancelled (null if not cancelled) renews_at: type: string format: date-time nullable: true description: When the subscription renews trial_end_date: type: string format: date-time nullable: true description: When the trial period ends post_trial_action: type: string nullable: true description: Action to take after trial ends plan_name: type: string nullable: true description: Name of the subscription plan plan_version: type: integer nullable: true description: Version number of the plan default_plan_id: type: string nullable: true description: ID of the default plan default_plan_name: type: string nullable: true description: Name of the default plan product_name: type: string description: Name of the product product_key: type: string description: Unique key for the product offering_key: type: string description: Unique key for the offering currency_code: type: string description: Currency code for billing created_at: type: string format: date-time description: When the subscription was created next_billing_date: type: string nullable: true description: Next billing date in human-readable format next_billing_amount: type: number nullable: true description: Amount for next billing current_billing_period_start: type: string format: date-time nullable: true description: Start of current billing period current_billing_period_end: type: string format: date-time nullable: true description: End of current billing period subscription_items: type: array items: type: object properties: price_option_id: type: string format: uuid description: Unique identifier for the price option name: type: string description: Name of the subscription item quantity: type: integer description: Quantity of the item unit_price: type: number nullable: true description: Unit price of the item (null for usage-based pricing) total_amount: type: number description: Total amount for the item billing_period_start: type: string format: date-time description: Start of the billing period for this item billing_period_end: type: string format: date-time description: End of the billing period for this item line_source_type: type: string description: Type of source for this line item (e.g., SubscriptionItem) is_addon: type: boolean description: Whether this item is an addon pricing: type: object nullable: true additionalProperties: true description: Pricing details (null if not applicable) currency_code: type: string description: Currency code for this item source_type: type: string description: >- Source type (e.g., ProductCatalogues::Offerings::Plan, ProductCatalogues::Entitlements::PaidEntitlement) source_id: type: string format: uuid description: Source identifier description: Array of subscription items with pricing details upcoming_invoice: allOf: - type: object nullable: true properties: invoice_id: type: string format: uuid description: Unique invoice identifier invoice_number: type: string nullable: true description: Invoice number (null if not yet assigned) amount: type: string description: Invoice amount currency: type: object properties: id: type: string format: uuid description: Unique currency identifier code: type: string description: Currency code (e.g., USD) name: type: string description: Currency name (e.g., US Dollar) country: type: string description: Country associated with the currency decimal_places: type: integer description: Number of decimal places for the currency symbol: type: string description: Currency symbol (e.g., $) is_active: type: boolean description: Whether the currency is active base_unit_name: type: string description: Name of the base unit (e.g., cents) base_unit_per_standard: type: integer description: Number of base units per standard unit (e.g., 100) created_at: type: string format: date-time description: When the currency was created updated_at: type: string format: date-time description: When the currency was last updated country_code: type: string description: Country code (e.g., US) due_date: type: string format: date-time description: Invoice due date status: type: string description: Invoice status (e.g., draft, pending, paid) nullable: true description: Details of the upcoming invoice PaymentMethodDetails: type: object properties: type: type: string description: Type of payment method (e.g., card, bank_account) brand: type: string nullable: true description: Brand of payment method (e.g., visa, mastercard) last4: type: string nullable: true description: Last four digits of card/account exp_month: type: string nullable: true description: Expiration month exp_year: type: string nullable: true description: Expiration year display_name: type: string nullable: true description: Display name for the payment method bank_name: type: string nullable: true description: Name of the bank (for bank accounts) securitySchemes: api_key: type: apiKey name: x-api-key in: header ````