{
  "openapi": "3.1.0",
  "info": {
    "title": "Baremetrics API",
    "description": "REST API for accessing subscription analytics data including MRR, ARR, churn rate, LTV, customer metrics, charges, subscriptions, plans, annotations, and revenue forecasting. Requires bearer token authentication using an API key from Baremetrics account settings.",
    "version": "1.0",
    "contact": {
      "url": "https://developers.baremetrics.com"
    }
  },
  "servers": [
    {
      "url": "https://api.baremetrics.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "bearer",
        "x-default": "APIKEY"
      }
    },
    "schemas": {
      "Charge": {
        "type": "object",
        "properties": {
          "oid": {
            "type": "string",
            "description": "Unique identifier for the charge in the source system."
          },
          "source_id": {
            "type": "string",
            "description": "The source identifier."
          },
          "source": {
            "type": "string",
            "description": "The source name (e.g. baremetrics, stripe)."
          },
          "status": {
            "type": "string",
            "description": "Status of the charge (e.g. paid, failed, refunded)."
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp when the charge was created."
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "subscription": {
            "type": "object",
            "nullable": true
          },
          "amount": {
            "type": "integer",
            "description": "Charge amount in cents."
          },
          "currency": {
            "type": "string",
            "description": "Currency code (e.g. USD)."
          },
          "original_amount": {
            "type": "integer",
            "description": "Original amount in cents before any adjustments."
          },
          "fee": {
            "type": "integer",
            "description": "Fee amount in cents."
          },
          "original_fee": {
            "type": "integer",
            "description": "Original fee in cents."
          }
        }
      },
      "Customer": {
        "type": "object",
        "properties": {
          "oid": {
            "type": "string",
            "description": "Unique identifier for the customer in the source system."
          },
          "source_id": {
            "type": "string",
            "description": "The source identifier."
          },
          "source": {
            "type": "string",
            "description": "The source name."
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp when the customer was created."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Customer email address."
          },
          "name": {
            "type": "string",
            "description": "Customer name."
          },
          "display_image": {
            "type": "string",
            "description": "URL to customer's display image."
          },
          "display_name": {
            "type": "string",
            "description": "Customer display name."
          },
          "notes": {
            "type": "string",
            "description": "Notes about the customer."
          },
          "ltv": {
            "type": "integer",
            "description": "Lifetime value in cents."
          }
        }
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "oid": {
            "type": "string",
            "description": "Unique identifier for the subscription in the source system."
          },
          "source_id": {
            "type": "string",
            "description": "The source identifier."
          },
          "source": {
            "type": "string",
            "description": "The source name."
          },
          "status": {
            "type": "string",
            "description": "Subscription status (e.g. active, canceled, trialing)."
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp when the subscription was created."
          },
          "customer": {
            "$ref": "#/components/schemas/Customer"
          },
          "plan": {
            "$ref": "#/components/schemas/Plan"
          },
          "mrr": {
            "type": "integer",
            "description": "Monthly recurring revenue in cents."
          },
          "quantity": {
            "type": "integer",
            "description": "Number of units subscribed."
          }
        }
      },
      "Plan": {
        "type": "object",
        "properties": {
          "oid": {
            "type": "string",
            "description": "Unique identifier for the plan in the source system."
          },
          "source_id": {
            "type": "string",
            "description": "The source identifier."
          },
          "source": {
            "type": "string",
            "description": "The source name."
          },
          "name": {
            "type": "string",
            "description": "Plan name."
          },
          "interval": {
            "type": "string",
            "description": "Billing interval (e.g. month, year)."
          },
          "interval_count": {
            "type": "integer",
            "description": "Number of intervals between billings."
          },
          "trial_duration": {
            "type": "integer",
            "description": "Trial duration in days."
          },
          "trial_duration_unit": {
            "type": "string",
            "description": "Unit for trial duration."
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp when the plan was created."
          },
          "active_subscriptions": {
            "type": "integer",
            "description": "Number of active subscriptions on this plan."
          },
          "amount": {
            "type": "integer",
            "description": "Plan amount in cents."
          },
          "currency": {
            "type": "string",
            "description": "Currency code."
          }
        }
      },
      "Annotation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier for the annotation."
          },
          "annotation": {
            "type": "string",
            "description": "The annotation text."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Date of the annotation."
          },
          "global": {
            "type": "boolean",
            "description": "Whether this annotation is global."
          },
          "metric": {
            "type": "string",
            "description": "The metric this annotation applies to."
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              }
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the event."
          },
          "type": {
            "type": "string",
            "description": "Event type (e.g. subscription.created, subscription.canceled, charge.created)."
          },
          "created": {
            "type": "integer",
            "description": "Unix timestamp when the event occurred."
          },
          "data": {
            "type": "object",
            "description": "Event payload data."
          }
        }
      },
      "Metric": {
        "type": "object",
        "properties": {
          "metric": {
            "type": "string",
            "description": "Metric name."
          },
          "summary": {
            "type": "object",
            "description": "Summary statistics for the metric.",
            "properties": {
              "current": {
                "type": "integer",
                "description": "Current value."
              },
              "previous": {
                "type": "integer",
                "description": "Previous period value."
              },
              "trend": {
                "type": "number",
                "description": "Percentage change."
              }
            }
          },
          "data": {
            "type": "array",
            "description": "Time-series data points.",
            "items": {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "value": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/{source_id}/charges": {
      "get": {
        "summary": "List Charges",
        "description": "Returns a list of charges for a given source.",
        "operationId": "list-charges",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "description": "Please see Sources for valid source IDs.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start",
            "in": "query",
            "description": "A unix timestamp for the start of the date range.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "A unix timestamp for the end of the date range.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "subscription_oid",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "customer_oid",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of charges",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "charges": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Charge"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    },
    "/v1/{source_id}/charges/{oid}": {
      "get": {
        "summary": "Show Charge",
        "description": "Returns a single charge by its OID.",
        "operationId": "show-charge",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "oid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A charge object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "charge": {
                      "$ref": "#/components/schemas/Charge"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/{source_id}/customers": {
      "get": {
        "summary": "List Customers",
        "description": "Returns a list of customers for a given source.",
        "operationId": "list-customers",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of customers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "customers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Customer"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/{source_id}/customers/{oid}": {
      "get": {
        "summary": "Show Customer",
        "description": "Returns a single customer by their OID.",
        "operationId": "show-customer",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "oid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A customer object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "customer": {
                      "$ref": "#/components/schemas/Customer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/{source_id}/subscriptions": {
      "get": {
        "summary": "List Subscriptions",
        "description": "Returns a list of subscriptions for a given source.",
        "operationId": "list-subscriptions",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "customer_oid",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscriptions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Subscription"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/{source_id}/subscriptions/{oid}": {
      "get": {
        "summary": "Show Subscription",
        "description": "Returns a single subscription by its OID.",
        "operationId": "show-subscription",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "oid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A subscription object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "subscription": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/{source_id}/events": {
      "get": {
        "summary": "List Events",
        "description": "Returns a list of events for a given source.",
        "operationId": "list-events",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start",
            "in": "query",
            "description": "A unix timestamp for the start of the date range.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "end",
            "in": "query",
            "description": "A unix timestamp for the end of the date range.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/metrics/{metric}": {
      "get": {
        "summary": "Show Metric",
        "description": "Returns a single metric summary (e.g. mrr, arr, ltv, customers, arpu, asp, customer_churn_rate, mrr_churn_rate, ltv, avg_sub_length).",
        "operationId": "show-metric",
        "parameters": [
          {
            "name": "metric",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["mrr", "arr", "ltv", "customers", "arpu", "asp", "customer_churn_rate", "mrr_churn_rate", "avg_sub_length", "new_customers", "new_mrr", "expansion_mrr", "contraction_mrr", "failed_charges", "failed_charges_mrr", "reactivations", "reactivations_mrr"]
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "description": "Start date in YYYY-MM-DD format.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "description": "End date in YYYY-MM-DD format.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metric data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "metric": {
                      "$ref": "#/components/schemas/Metric"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/{source_id}/plans": {
      "get": {
        "summary": "List Plans",
        "description": "Returns a list of plans for a given source.",
        "operationId": "list-plans",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of plans",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plans": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Plan"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/{source_id}/plans/{oid}": {
      "get": {
        "summary": "Show Plan",
        "description": "Returns a single plan by its OID.",
        "operationId": "show-plan",
        "parameters": [
          {
            "name": "source_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "oid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A plan object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plan": {
                      "$ref": "#/components/schemas/Plan"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/annotations": {
      "get": {
        "summary": "List Annotations",
        "description": "Returns a list of annotations.",
        "operationId": "list-annotations",
        "parameters": [],
        "responses": {
          "200": {
            "description": "A list of annotations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "annotations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Annotation"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create Annotation",
        "description": "Creates a new annotation.",
        "operationId": "create-annotation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "annotation": {
                    "type": "string",
                    "description": "The annotation text."
                  },
                  "date": {
                    "type": "string",
                    "format": "date",
                    "description": "The date for the annotation in YYYY-MM-DD format."
                  },
                  "global": {
                    "type": "boolean",
                    "description": "Whether the annotation is global."
                  },
                  "metric": {
                    "type": "string",
                    "description": "The metric this annotation applies to."
                  },
                  "user_id": {
                    "type": "integer",
                    "description": "The user ID creating the annotation."
                  }
                },
                "required": ["annotation", "date"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created annotation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "annotation": {
                      "$ref": "#/components/schemas/Annotation"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/annotations/{id}": {
      "get": {
        "summary": "Show Annotation",
        "description": "Returns a single annotation by its ID.",
        "operationId": "show-annotation",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "An annotation object",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "annotation": {
                      "$ref": "#/components/schemas/Annotation"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete Annotation",
        "description": "Deletes an annotation by its ID.",
        "operationId": "delete-annotation",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Annotation deleted"
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": false
  }
}