{
    "openapi": "3.0.1",
    "servers": [
        {
            "url": "https://staging.crossmint.com/api",
            "description": "Staging environment (testnets)"
        },
        {
            "url": "https://www.crossmint.com/api",
            "description": "Production environment (mainnets)"
        }
    ],
    "security": [
        {
            "apiKey": []
        }
    ],
    "info": {
        "description": "N/A",
        "version": "1.0.0",
        "title": "Subscription APIs",
        "contact": {
            "name": "Crossmint Subscription APIs",
            "url": "https://www.crossmint.com",
            "email": "support@crossmint.com"
        }
    },
    "paths": {
        "/2022-06-09/subscriptions/{subscriptionLocator}/cancel": {
            "patch": {
                "summary": "Cancel Subscription",
                "description": "Cancel an existing subscription, which stops recurring payments for the specified token. The token will remain active until the end of the billing period.\n\n**API scope required**: `subscriptions.update`\n",
                "operationId": "cancel-subscription",
                "tags": ["Subscriptions"],
                "parameters": [
                    {
                        "name": "subscriptionLocator",
                        "in": "path",
                        "description": "The unique identifier for the subscription, formatted as `chain:contractAddress:tokenId`.\nThis locator references the specific token associated with the subscription.\n",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "base:0x1234567890123456789012345678901234567890:1"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Subscription successfully cancelled.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid arguments or bad request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/400Response"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden error, please ensure the credentials are correct.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/403Response"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Subscription not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/404ResponseCancel"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/503Response"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/2022-06-09/subscriptions/{subscriptionLocator}": {
            "get": {
                "summary": "Subscription Information",
                "description": "Retrieve information about an existing subscription, including expiry time, payment information and recurrency status.\n\n**API scope required**: `subscriptions.read`\n",
                "operationId": "get-subscription",
                "tags": ["Subscriptions"],
                "parameters": [
                    {
                        "name": "subscriptionLocator",
                        "in": "path",
                        "description": "The unique identifier for the subscription, formatted as `chain:contractAddress:tokenId`.\nThis locator references the specific token associated with the subscription.\n",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "base:0x1234567890123456789012345678901234567890:1"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Subscription information",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SubscriptionDto"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid arguments or bad request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/400Response"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden error, please ensure the credentials are correct.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/403Response"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Subscription not found.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/404Response"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/503Response"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "apiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-KEY",
                "description": "Obtained in the Crossmint developer console"
            }
        },
        "schemas": {
            "400Response": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "boolean",
                        "example": true
                    },
                    "message": {
                        "type": "string",
                        "example": "Invalid subscription ID format or missing required parameters."
                    }
                }
            },
            "403Response": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "boolean",
                        "example": true
                    },
                    "message": {
                        "type": "string",
                        "example": "API key provided doesn't have the required scopes or is invalid."
                    }
                }
            },
            "404ResponseCancel": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "boolean",
                        "example": true
                    },
                    "message": {
                        "type": "string",
                        "example": "Subscription not found or has already been cancelled."
                    }
                }
            },
            "404Response": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "boolean",
                        "example": true
                    },
                    "message": {
                        "type": "string",
                        "example": "Subscription not found."
                    }
                }
            },
            "503Response": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "boolean",
                        "example": true
                    },
                    "message": {
                        "type": "string",
                        "example": "Service is temporarily unavailable. Please try again later or contact support if the issue persists."
                    }
                }
            },
            "SubscriptionDto": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": ["active", "expired"]
                    },
                    "expiresAt": {
                        "type": "number",
                        "example": 1731984105000
                    },
                    "tokenLocator": {
                        "type": "string",
                        "example": "base:0xdC46584d76aCcc879d682Ed2d9c7338f8FdbF1cC:1"
                    },
                    "collection": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string",
                                "example": "28c5bc10-1964-4d94-b45b-0e1dab1cd346"
                            }
                        },
                        "required": ["id"]
                    },
                    "owner": {
                        "type": "string",
                        "example": "0x62e2cb5f9Ac87cf91358395fdB6797ADb7EA9E38"
                    },
                    "payment": {
                        "type": "object",
                        "properties": {
                            "type": {
                                "type": "string",
                                "enum": ["recurring-credit-card"]
                            },
                            "status": {
                                "type": "string",
                                "enum": ["active", "cancelled"]
                            },
                            "recurring": {
                                "type": "object",
                                "properties": {
                                    "interval": {
                                        "type": "string",
                                        "enum": ["month"]
                                    },
                                    "intervalCount": {
                                        "type": "number",
                                        "enum": [1]
                                    }
                                },
                                "required": ["interval", "intervalCount"]
                            },
                            "lastChargeDate": {
                                "type": "number",
                                "example": 1731984105000
                            },
                            "nextChargeDate": {
                                "type": "number",
                                "example": 1731984105000
                            }
                        },
                        "required": ["type", "status", "recurring", "lastChargeDate", "nextChargeDate"]
                    }
                },
                "required": ["status", "expiresAt", "tokenLocator", "collection", "owner", "payment"]
            }
        }
    }
}