{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/api/v1/donations/create": {
      "post": {
        "summary": "Create a donation",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Creates a donation to any nonprofit. CHANGE keeps track of your donations, bills you at the end of the month, and handles the nonprofit payouts for you.",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The amount of the donation in cents.",
            "examples": {
              "five": {
                "value": 500,
                "summary": "A $5.00 donation."
              }
            }
          },
          {
            "name": "nonprofit_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The id of a nonprofit from the CHANGE network.",
            "examples": {
              "watsi": {
                "value": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
                "summary": "The id for Watsi (https://watsi.org)"
              }
            }
          },
          {
            "name": "funding_source",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "merchant",
                "customer"
              ]
            },
            "description": "Source of the donation funds. If you are collecting payment from your customer for the donation, use `customer`.",
            "examples": {
              "customer": {
                "value": "customer",
                "summary": "A customer-funded donation."
              }
            }
          },
          {
            "name": "zip_code",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "The customer's zip code. Provide this to unlock geographic insights.",
            "examples": {
              "valid": {
                "value": "94104",
                "summary": "A valid zip code."
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Donation successful",
            "content": {
              "application/json": {
                "example": {
                  "amount": 500,
                  "id": "d_ZMHGi4XOLbIZNCcRdNQIYRMD",
                  "live_mode": true,
                  "merchant_id": "m_ZRXrC36KAICbIBccukOYrpz2",
                  "nonprofit_id": "n_t97eaBKgDzIiZpaB5miAGqmW",
                  "order_value": null,
                  "zip_code": "94104",
                  "external_id": null
                }
              }
            }
          },
          "400": {
            "description": "Param `nonprofit_id` invalid",
            "content": {
              "application/json": {
                "example": {
                  "status": 400,
                  "code": "nonprofit_invalid",
                  "title": "The nonprofit is invalid. Please reference a nonprofit in the CHANGE network.",
                  "detail": "nonprofit_id n_invalid is invalid."
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/donations/show": {
      "get": {
        "summary": "Retrieve a donation",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Retrieves the details of a donation you've previously made.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The id of a donation. Ids are returned when a donation is created.",
            "examples": {
              "donation": {
                "value": "d_NuYL6M2C1kjecXpWzKVODw7W",
                "summary": "A donation id."
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "example": {
                  "amount": 296,
                  "id": "d_lrUNd3aQfnwLYzSRu6mrk4ZA",
                  "live_mode": true,
                  "merchant_id": "m_CgzKWshXuPcI8nPKH8QZoeqL",
                  "nonprofit_id": "n_h3ni9x9pH7OAkHXyghL2wjSZ",
                  "order_value": 1007,
                  "zip_code": "51689",
                  "external_id": null
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/donations/index": {
      "get": {
        "summary": "List your donations",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Retrieves a list of donations you've previously made. The donations are returned in order of creation, with the most recent donations appearing first. This endpoint is paginated.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Which page to return. This endpoint is paginated, and returns maximum 30 donations per page.",
            "examples": {
              "page 1": {
                "value": "1",
                "summary": "The first 30 donations."
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "example": {
                  "donations": [
                    {
                      "id": 6236,
                      "amount": 234,
                      "created_at": "2021-05-05T20:18:05.494Z",
                      "updated_at": "2021-05-05T20:18:05.494Z",
                      "invoice_id": 3078,
                      "nonprofit_id": 8202,
                      "merchant_id": 5966,
                      "customer_funded": true,
                      "public_id": "d_U0M2sPsQpsKXx6d3XOInsOu4",
                      "zip_code": "46076-9506",
                      "region": null,
                      "order_value": 2526,
                      "external_id": null,
                      "sandbox": false
                    },
                    {
                      "id": 6235,
                      "amount": 335,
                      "created_at": "2021-05-05T20:18:05.482Z",
                      "updated_at": "2021-05-05T20:18:05.482Z",
                      "invoice_id": 3078,
                      "nonprofit_id": 8201,
                      "merchant_id": 5966,
                      "customer_funded": true,
                      "public_id": "d_nbvCMyqXdFyHvEFn98NZi281",
                      "zip_code": "71778",
                      "region": null,
                      "order_value": 2688,
                      "external_id": null,
                      "sandbox": false
                    }
                  ],
                  "page": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/donations/carbon_calculate": {
      "get": {
        "summary": "Calculate shipping carbon offset",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Calculates the donation amount (to CarbonFund 501\\(c\\)3) needed to offset a physical shipment. This calculation depends on the weight, primary transportation method, and distance of the shipment. Provide the distance of the shipment using the origin and destination address, or directly with the number of miles. For convenience, this endpoint also returns the id of the nonprofit CarbonFund, for making a subsequent donation to. See the [Carbon offsets guide](/recipes/carbon-offsets/) for more on using this endpoint.",
        "parameters": [
          {
            "name": "origin_address",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "The origin zip code (US only) of the shipment. If you send this parameter, also send `destination_address`.",
            "examples": {
              "illinois": {
                "value": 60148,
                "summary": "An Illinois zip code."
              }
            }
          },
          {
            "name": "destination_address",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "The destination zip code (US only) of the shipment. If you send this parameter, also send `origin_address`.",
            "examples": {
              "california": {
                "value": 94133,
                "summary": "A California zip code."
              }
            }
          },
          {
            "name": "distance_mi",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "The total distance (in miles) of the shipment. You can use this parameter in place of `origin_address` and `destination_address`."
          },
          {
            "name": "weight_lb",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "The total weight (in pounds) of the shipment.",
            "examples": {
              "3.5": {
                "value": 3.5,
                "summary": "A 3.5 pound shipment."
              }
            }
          },
          {
            "name": "transportation_method",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "air",
                "truck",
                "rail",
                "sea"
              ]
            },
            "description": "The primary transportation method of the shipment.",
            "examples": {
              "air": {
                "value": "air",
                "summary": "The shipment will be primarily by plane."
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "example": {
                  "amount": 18,
                  "nonprofit_id": "n_l8vRRYrxhw0ei8AMYto5FzU1"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/donations/crypto_calculate": {
      "get": {
        "summary": "Calculate crypto carbon offset",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Calculates the donation amount (to CarbonFund 501\\(c\\)3) needed to offset a cryptocurrency transaction. For convenience, this endpoint also returns the id of the nonprofit CarbonFund, for making a subsequent donation to. See the [Carbon offsets guide](/recipes/carbon-offsets/) for more on using this endpoint.",
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "The number of transactions to offset.",
            "examples": {
              "two": {
                "value": 2,
                "summary": "Represents two transactions."
              }
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "eth",
                "btc"
              ]
            },
            "description": "The currency of the transaction.",
            "examples": {
              "ethereum": {
                "value": "eth",
                "summary": "The ETH currency."
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "example": {
                  "amount": 34,
                  "nonprofit_id": "n_l8vRRYrxhw0ei8AMYto5FzU1"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/donations/carbon_stats": {
      "get": {
        "summary": "Retrieve carbon offset stats",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Measures your carbon offset impact in relatable terms. Provide the id of a donation to CarbonFund to see stats about that specific donation. If you omit the donation id, this endpoint returns aggregate stats for all of your CarbonFund donations.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "The id of a donation to the CarbonFund nonprofit. Ids are returned when a donation is created. If an ID is not provided, the total stats for all donations to CarbonFund are returned.",
            "examples": {
              "donation": {
                "value": "d_NuYL6M2C1kjecXpWzKVODw7W",
                "summary": "A donation id."
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "example": {
                  "amount": 107,
                  "trees": 1.8,
                  "co2_tonnes_offset": 0.107
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/nonprofits/show": {
      "get": {
        "summary": "Show a nonprofit",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Retrieves information for a nonprofit.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The id of a nonprofit from the CHANGE network.",
            "examples": {
              "watsi": {
                "value": "n_IfEoPCaPqVsFAUI5xl0CBUOx",
                "summary": "The id for Watsi (https://watsi.org)"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Show successful",
            "content": {
              "application/json": {
                "example": {
                  "icon_url": "https://nonprofit-icons.s3-us-west-1.amazonaws.com/C.png",
                  "id": "n_LLWKUimvwSZ9A01gTdFo0uJe",
                  "name": "BERNIER-GIBSON",
                  "ein": "057310526",
                  "memo": null,
                  "address_line": "8236 Leslie Gateway",
                  "city": "Port Jasmineview",
                  "classification": "C62",
                  "mission": "Triple-buffered disintermediate projection",
                  "state": "New Jersey",
                  "website": "http://ziemann.co/rosalind",
                  "zip_code": "16409-3215"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/nonprofits/list": {
      "get": {
        "summary": "Search a nonprofit",
        "security": [
          {
            "basic_auth": [

            ]
          }
        ],
        "description": "Retrieves a list of nonprofits whose names match the provided name. This endpoint is paginated.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "A string to search.",
            "examples": {
              "some nonprofit": {
                "value": "Some Nonprofit",
                "summary": "The name of some nonprofit."
              }
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "The page to return. This endpoint is paginated, and returns up to 30 nonprofits at a time.",
            "examples": {
              "page 1": {
                "value": "1",
                "summary": "The first 30 nonprofits."
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List successful",
            "content": {
              "application/json": {
                "example": {
                  "nonprofits": [
                    {
                      "id": "n_Q0Pwyjw5H1GDCviVvJXbXAJF",
                      "name": "SOME NONPROFIT",
                      "ein": "158336879",
                      "memo": null,
                      "last_verified_at": null,
                      "mission": "Persistent 24 hour solution",
                      "address_line": "7510 Sanford Mountain",
                      "state": "Tennessee",
                      "city": "Reicheltown",
                      "zip_code": "07815-9329",
                      "website": "http://abshire.info/ellsworth.kris",
                      "classification": "Y18",
                      "icon_url": "https://nonprofit-icons.s3-us-west-1.amazonaws.com/Y.png"
                    }
                  ],
                  "page": 1
                }
              }
            }
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://{defaultHost}",
      "variables": {
        "defaultHost": {
          "default": "api.getchange.io"
        }
      }
    }
  ],
  "components": {
    "securitySchemes": {
      "basic_auth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}